mirror of https://github.com/stenzek/duckstation
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
118 lines
5.1 KiB
Markdown
118 lines
5.1 KiB
Markdown
# libcubeb - Cross-platform Audio I/O Library
|
|
|
|
[](https://github.com/mozilla/cubeb/actions/workflows/build.yml)
|
|
|
|
`libcubeb` is a cross-platform C library for high and low-latency audio input/output. It provides a simple, consistent API for audio playback and recording across multiple platforms and audio backends. It is written in C, C++ and Rust, with a C ABI and [Rust](https://github.com/mozilla/cubeb-rs) bindings. While originally written for use in the Firefox Web browser, a number of other software projects have adopted it.
|
|
|
|
## Features
|
|
|
|
- **Cross-platform support**: Windows, macOS, Linux, Android, and other platforms
|
|
- **Versatile**: Optimized for low-latency real-time audio applications, or power efficient higher latency playback
|
|
- **A/V sync**: Latency compensated audio clock reporting for easy audio/video synchronization
|
|
- **Full-duplex support**: Simultaneous audio input and output, reclocked
|
|
- **Device enumeration**: Query available audio devices
|
|
- **Audio processing for speech**: Can use VoiceProcessing IO on recent macOS
|
|
|
|
## Supported Backends & status
|
|
|
|
| *Backend* | *Support Level* | *Platform version* | *Notes* |
|
|
|-------------------|-----------------|--------------------|--------------------------------------------------|
|
|
| PulseAudio (Rust) | Tier-1 | | Main Linux desktop backend |
|
|
| AudioUnit (Rust) | Tier-1 | | Main macOS backend |
|
|
| WASAPI | Tier-1 | Windows >= 7 | Main Windows backend |
|
|
| AAudio | Tier-1 | Android >= 8 | Main Android backend for most devices |
|
|
| OpenSL | Tier-1 | Android >= 2.3 | Android backend for older devices |
|
|
| OSS | Tier-2 | | |
|
|
| sndio | Tier-2 | | |
|
|
| Sun | Tier-2 | | |
|
|
| WinMM | Tier-3 | Windows XP | Was Tier-1, Firefox minimum Windows version 7. |
|
|
| AudioTrack | Tier-3 | Android < 2.3 | Was Tier-1, Firefox minimum Android version 4.1. |
|
|
| ALSA | Tier-3 | | |
|
|
| JACK | Tier-3 | | |
|
|
| KAI | Tier-3 | | |
|
|
| PulseAudio (C) | Tier-4 | | Was Tier-1, superseded by Rust |
|
|
| AudioUnit (C++) | Tier-4 | | Was Tier-1, superseded by Rust |
|
|
|
|
Tier-1: Actively maintained. Should have CI coverage. Critical for Firefox.
|
|
|
|
Tier-2: Actively maintained by contributors. CI coverage appreciated.
|
|
|
|
Tier-3: Maintainers/patches accepted. Status unclear.
|
|
|
|
Tier-4: Deprecated, obsolete. Scheduled to be removed.
|
|
|
|
Note that the support level is not a judgement of the relative merits
|
|
of a backend, only the current state of support, which is informed
|
|
by Firefox's needs, the responsiveness of a backend's
|
|
maintainer, and the level of contributions to that backend.
|
|
|
|
## Building
|
|
|
|
### Prerequisites
|
|
|
|
- CMake 3.15 or later
|
|
- Non-ancient MSVC, clang or gcc, for compiling both C and C++
|
|
- Platform-specific audio libraries (automatically detected)
|
|
- Optional but recommended: Rust compiler to compile and link more recent backends for macOS and PulseAudio
|
|
|
|
### Quick build
|
|
|
|
```bash
|
|
git clone https://github.com/mozilla/cubeb.git
|
|
cd cubeb
|
|
cmake -B build
|
|
cmake --build build
|
|
```
|
|
|
|
### Better build with Rust backends
|
|
|
|
```bash
|
|
git clone --recursive https://github.com/mozilla/cubeb.git
|
|
cd cubeb
|
|
cmake -B build -DBUILD_RUST_LIBS=ON
|
|
cmake --build build
|
|
```
|
|
|
|
### Platform-Specific Notes
|
|
|
|
**Windows**: Supports Visual Studio 2015+ and MinGW-w64. Use `-G "Visual Studio 16 2019"` or `-G "MinGW Makefiles"`.
|
|
|
|
**macOS**: Requires Xcode command line tools. Audio frameworks are automatically linked.
|
|
|
|
**Linux**: Development packages for desired backends:
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt-get install libpulse-dev libasound2-dev libjack-dev
|
|
|
|
# Fedora/RHEL
|
|
sudo dnf install pulseaudio-libs-devel alsa-lib-devel jack-audio-connection-kit-devel
|
|
```
|
|
|
|
**Android**: Use with Android NDK. AAudio requires API level 26+.
|
|
|
|
## Testing
|
|
|
|
Run the test suite:
|
|
```bash
|
|
cd build
|
|
ctest
|
|
```
|
|
|
|
Use the interactive test tool:
|
|
```bash
|
|
./cubeb-test
|
|
```
|
|
|
|
## License
|
|
|
|
Licensed under an ISC-style license. See [LICENSE](LICENSE) for details.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please see the [contribution guidelines](CONTRIBUTING.md) and check the [issue tracker](https://github.com/mozilla/cubeb/issues).
|
|
|
|
## Links
|
|
|
|
- [GitHub Repository](https://github.com/mozilla/cubeb)
|
|
- [API Documentation](https://mozilla.github.io/cubeb/)
|