cubeb-coreaudio-rs/README.md

cubeb-coreaudio-rs

Rust implementation of Cubeb on the MacOS platform.

Current Goals

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

Status

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

Install

Install cubeb-coreaudio within cubeb

Run the following command:

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

Issues

• Atomic:
  • We need atomic type around f32 but there is no this type in the stardard Rust
  • Using atomic-rs to do this.
• kAudioDevicePropertyBufferFrameSize cannot be set when another stream using the same device with smaller buffer size is active. See here 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

Branches

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