1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
# cubeb-coreaudio-rs
[](https://circleci.com/gh/mozilla/cubeb-coreaudio-rs)
[](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
|
