2.0.0

Author: mrDIMAS

.github/workflows/ci.yml

@@ -1,5 +1,5 @@
 name: CI
-on: [push, pull_request]
+on: [ push, pull_request ]
 env:
   CARGO_TERM_COLOR: always
   RUSTFLAGS: --deny warnings
@@ -11,8 +11,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        rust: [stable]
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        rust: [ stable ]
+        os: [ ubuntu-latest, windows-latest, macos-latest ]
     steps:
       - uses: actions/checkout@v2
       - uses: actions-rs/toolchain@v1
@@ -38,7 +38,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        rust: [stable]
+        rust: [ stable ]
     steps:
       - uses: actions/checkout@v2
       - uses: actions-rs/toolchain@v1
@@ -83,21 +83,21 @@ jobs:
     name: iOS CI
     runs-on: macOS-latest
     steps:
-    - uses: actions/checkout@v2
-    - name: Install dependencies
-      run: brew install llvm
-    - name: Install stable
-      uses: actions-rs/toolchain@v1
-      with:
-        profile: minimal
-        toolchain: stable
-        override: true
-    - name: Add iOS targets
-      run: rustup target add aarch64-apple-ios x86_64-apple-ios
-    - name: Build aarch64
-      run: cargo check --verbose --workspace --target=aarch64-apple-ios --all-features
-    - name: Build x86_64
-      run: cargo check --verbose --workspace --target=x86_64-apple-ios --all-features
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: brew install llvm
+      - name: Install stable
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+          override: true
+      - name: Add iOS targets
+        run: rustup target add aarch64-apple-ios x86_64-apple-ios
+      - name: Build aarch64
+        run: cargo check --verbose --workspace --target=aarch64-apple-ios --all-features
+      - name: Build x86_64
+        run: cargo check --verbose --workspace --target=x86_64-apple-ios --all-features
 
   format:
     name: Rustfmt CI
@@ -123,7 +123,7 @@ jobs:
       - name: Install Dependencies
         run: |
           sudo apt-get update # Run update first or install might start failing eventually
-          sudo apt-get install --no-install-recommends -y libasound2-dev libudev-dev pkg-config
+          sudo apt-get install --no-install-recommends -y libasound2-dev libpulse-dev libudev-dev pkg-config
       - run: cargo clippy --version
       - run: cargo clippy --workspace --all-targets --all-features -- --deny warnings
 

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 2.0.0
+
+- PulseAudio support for Linux. See `README.md` for detailed instructions of how to use it.
+
 # 1.1.0
 
 - Migrated to `ndk` crate instead of `aaudio`, which is unmaintained and has build problems (see

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tinyaudio"
-version = "1.1.0"
+version = "2.0.0"
 edition = "2021"
 license = "MIT"
 description = "TinyAudio is a cross-platform, easy-to-use, low-level, audio output library."

README.md

@@ -1,14 +1,14 @@
 # TinyAudio
 
-TinyAudio is a cross-platform audio output library. Its main goal to provide unified access to
+TinyAudio is a cross-platform audio output library. Its main goal is to provide unified access to
 a default sound output device of your operating system as easy as possible, covering as many platforms
 such as PC (Windows, Linux, macOS), Mobile Devices (Android, iOS), and WebAssembly.
 
 ## What this crate can do
 
 The crate just takes the data you've prepared and sends it to a default operating system's sound output
 device. It uses floating-point audio samples and converts them to the closest supported platform-dependent
-format automatically. The crate guarantees, that the intermediate data buffer will always be of requested size.
+format automatically. The crate guarantees that the intermediate data buffer will always be of requested size.
 Use this crate, if you need to play your audio samples as easy as possible.
 
 ## What this crate cannot do
@@ -21,29 +21,53 @@ selection, querying of supported formats, input capturing (i.e. from microphone)
 
 | Windows | Linux | macOS | WebAssembly | Android | iOS |
 |---------|-------|-------|-------------|---------|-----|
-| ✅       | ✅     | ✅    | ✅           | ✅       | ✅  |
+| ✅       | ✅     | ✅     | ✅           | ✅       | ✅   |
 
 ## How it works
 
 The crate internally creates an audio output context and uses a user-defined callback to supply the device
 with samples to play. The callback will be called periodically to generate new data; it will be called util
-the device instance is "alive". In other words this crate performs the simplest audio streaming.
+the device instance is "alive". In other words, this crate performs the simplest audio streaming.
 
 ## Android details
 
-This crate uses `AAudio` for audio output on Android platform. `AAudio` is quite new API, which was added in ~2017 
+This crate uses `AAudio` for audio output on Android platform. `AAudio` is quite new API, which was added in ~2017
 (in Android 8.1 Oreo). This means that you have to use `API Level 26+` to get the crate up and running. Also, you must
-initialize an audio device only after your application has gained focus (`GainedFocus` event in `android-activity` crate),
-otherwise device creation will fail. See `android-examples` 
-[directory](https://github.com/mrDIMAS/tinyaudio/tree/main/android-examples) for examples. 
+initialize an audio device only after your application has gained focus (`GainedFocus` event in `android-activity`
+crate), otherwise device creation will fail. See `android-examples`
+[directory](https://github.com/mrDIMAS/tinyaudio/tree/main/android-examples) for examples.
 
 ## WebAssembly details
 
-Most of the web browsers nowadays requires a "confirmation" action from a user (usually a button click or something similar) to 
-allow a web page to play an audio. This means that you must initialize an audio device _only_ after some action on
-a web page that runs your WebAssembly package. In the simplest scenario it could be a simple button with a callback
-that initializes an audio device. See `wasm-examples` [directory](https://github.com/mrDIMAS/tinyaudio/tree/main/wasm-examples)
-for examples.
+Most of the web browsers nowadays require a "confirmation" action from a user (usually a button click or something
+similar) to allow a web page to play an audio. This means that you must initialize an audio device _only_ after some
+action on
+a web page that runs your WebAssembly package. In the simplest scenario, it could be a simple button with a callback
+that initializes an audio device. See `wasm-examples`
+[directory](https://github.com/mrDIMAS/tinyaudio/tree/main/wasm-examples) for examples.
+
+## Linux details
+
+Do not forget to install the required development libraries, otherwise the crate won't compile:
+
+```shell
+sudo apt-get install libasound2-dev libudev-dev pkg-config
+```
+
+### Backends
+
+Linux supports two audio "backends" - `ALSA` and `PulseAudio`. By default, this crate uses `ALSA`, but this can be
+changed by specifying the `pulse` feature:
+
+```toml
+tinyaudio = { version = "2", default-features = false, features = ["pulse"] }
+```
+
+`PulseAudio` backend requires `libpulse-dev` to be installed:
+
+```shell
+sudo apt-get install libpulse-dev
+```
 
 ## Examples
 
@@ -110,7 +134,7 @@ from `cpal` with the example from the above code snippet. The next main differen
 that the size of the output buffer will be exactly the same as requested during the creation of audio stream, while
 `TinyAudio` strictly guarantees this. Having a buffer of fixed size could be mandatory for some algorithms (such as
 HRTF). That last main difference is fixed sample format - it is guaranteed to be `f32`. This simplifies a lot of
-algorithms and have almost the same performance as with integer samples on relatively modern hardware.
+algorithms and has almost the same performance as with integer samples on relatively modern hardware.
 
 Feature-parity with `cpal` is not a goal for this library, its main goal is to do one particular task, but do it as well
 as possible.