cubeb-coreaudio-rs/README.md

# cubeb-coreaudio-rs

[![CircleCI](https://circleci.com/gh/mozilla/cubeb-coreaudio-rs.svg?style=svg)](https://circleci.com/gh/mozilla/cubeb-coreaudio-rs)
[![Build & Test](https://github.com/mozilla/cubeb-coreaudio-rs/actions/workflows/test.yml/badge.svg)](https://github.com/mozilla/cubeb-coreaudio-rs/actions/workflows/test.yml)

*Rust* implementation of [Cubeb][cubeb] on [the MacOS platform][cubeb-au].

## Current Goals

- Keep refactoring the implementation until it looks rusty! (it's translated from C at first.)
  - Check the [todo list][todo]

## Status

This is now the _Firefox_'s default audio backend on *Mac OS*.

## Install

### Install cubeb-coreaudio within cubeb

Run the following command:
```sh
curl https://raw.githubusercontent.com/mozilla/cubeb-coreaudio-rs/trailblazer/build-audiounit-rust-in-cubeb.sh | sh
```

### Other

Just clone this repo

## Test

Please run `sh run_tests.sh`.

Some tests cannot be run in parallel.
They may operate the same device at the same time,
or indirectly fire some system events that are listened by some tests.

The tests that may affect others are marked `#[ignore]`.
They will be run by `cargo test ... -- --ignored ...`
after finishing normal tests.
Most of the tests are executed in `run_tests.sh`.
Only those tests commented with *FIXME* are left.

### Git Hooks

You can install _git hooks_ by running `install_git_hook.sh`.
Then _pre-push_ script will be run and do the `cargo fmt` and `cargo clippy` check
before the commits are pushed to remote.

### Run Sanitizers

Run _AddressSanitizer (ASan), LeakSanitizer (LSan), MemorySanitizer (MSan), ThreadSanitizer (TSan)_
by `sh run_sanitizers.sh`.

The above command will run all the test suits in *run_tests.sh* by all the available _sanitizers_.
However, it takes a long time for finshing the tests.

### Device Tests

Run `run_device_tests.sh`.

If you'd like to run all the device tests with sanitizers,
use `RUSTFLAGS="-Z sanitizer=<SAN>" sh run_device_tests.sh`
with valid `<SAN>` such as `address` or `thread`.

#### Device Switching

The system default device will be changed during our tests.
All the available devices will take turns being the system default device.
However, after finishing the tests, the default device will be set to the original one.
The sounds in the tests should be able to continue whatever the system default device is.

#### Device Plugging/Unplugging

We implement APIs simulating plugging or unplugging a device
by adding or removing an aggregate device programmatically.
It's used to verify our callbacks for minitoring the system devices work.

### Manual Test

- Output devices switching
  - `$ cargo test test_switch_output_device -- --ignored --nocapture`
  - Enter `s` to switch output devices
  - Enter `q` to finish test
- Device collection change
  - `cargo test test_device_collection_change -- --ignored --nocapture`
  - Plug/Unplug devices to see events log.
- Manual Stream Tester
  - `cargo test test_stream_tester -- --ignored --nocapture`
    - `c` to create a stream
    - `d` to destroy a stream
    - `s` to start the created stream
    - `t` to stop the created stream
    - `r` to register a device changed callback to the created stream
    - `v` to set volume to the created stream
    - `q` to quit the test
  - It's useful to simulate the stream bahavior to reproduce the bug we found,
    with some modified code.

## TODO

See [todo list][todo]

## Issues

- Atomic:
  - We need atomic type around `f32` but there is no this type in the stardard Rust
  - Using [atomic-rs](https://github.com/Amanieu/atomic-rs) to do this.
- `kAudioDevicePropertyBufferFrameSize` cannot be set when another stream using the same device with smaller buffer size is active. See [here][chg-buf-sz] for details.

### Test issues

- Fail to run tests that depend on `AggregateDevice::create_blank_device` with the tests that work with the device event listeners
  - The `AggregateDevice::create_blank_device` will add an aggregate device to the system and fire the device-change events indirectly.
- `TestDeviceSwitcher` cannot work when there is an alive full-duplex stream
  - An aggregate device will be created for a duplex stream when its input and output devices are different.
  - `TestDeviceSwitcher` will cached the available devices, upon it's created, as the candidates for default device
  - Hence the created aggregate device may be cached in `TestDeviceSwitcher`
  - If the aggregate device is destroyed (when the destroying the duplex stream created it) but the `TestDeviceSwitcher` is still working,
    it will set a destroyed device as the default device
  - See details in [device_change.rs](src/backend/tests/device_change.rs)

## Branches

- [trailblazer][trailblazer]: Main branch
- [plain-translation-from-c][from-c]: The code is rewritten from C code on a line-by-line basis
- [ocs-disposal][ocs-disposal]: The first version that replace our custom mutex by Rust Mutex

[cubeb]: https://github.com/mozilla/cubeb "Cross platform audio library"
[cubeb-au]: https://github.com/mozilla/cubeb/blob/master/src/cubeb_audiounit.cpp "Cubeb AudioUnit"

[chg-buf-sz]: https://cs.chromium.org/chromium/src/media/audio/mac/audio_manager_mac.cc?l=982-989&rcl=0207eefb445f9855c2ed46280cb835b6f08bdb30 "issue on changing buffer size"

[todo]: todo.md

[bmo1572273]: https://bugzilla.mozilla.org/show_bug.cgi?id=1572273
[bmo1572273-c13]: https://bugzilla.mozilla.org/show_bug.cgi?id=1572273#c13

[from-c]: https://github.com/mozilla/cubeb-coreaudio-rs/tree/plain-translation-from-c
[ocs-disposal]: https://github.com/mozilla/cubeb-coreaudio-rs/tree/ocs-disposal
[trailblazer]: https://github.com/mozilla/cubeb-coreaudio-rs/tree/trailblazer