sansan is a real-time music playback library.
This library is for:
- Queue-based, real-time music playback
- Live audio state reading/writing without blocking
- Audio metadata reading (
ID3/Vorbistags) - OS media control integration
This library is not:
- A general purpose audio playback library
sansan is built with music players in-mind - it is meant to be the part
of the system that handles the real-time audio decoding/playback,
while exposing an audio state read/write API that is non-blocking.
Although sansan can be used for general purpose audio playback,
it does not include general purpose audio APIs like mixing, filters, multiple tracks, etc.
The book at https://sansan.cat is the main user documentation. It holds all the information needed to get started with sansan - what things there are, what they do, how to use them.
The library documentation at https://docs.rs/sansan is the API reference, documenting inputs and outputs and other note-worthy things about the API, although, it does not contain detailed commentary on usage, how things work together, etc.
For more example usage of sansan, see examples/.
This example shows some basic usage of sansan:
- Creating the
Engine - Adding music to the queue
- Sending signals to the
Engine(play, next) - Reading/writing live audio state without blocking
// TODOsansan's abstract design is documented in DESIGN.md.
This purpose of DESIGN.md is to act as a reference to allow for easier changes in the future.
Although, it mostly covers the system-wide view and does not include implementation details. For example, the real-time audio sample buffer - how big should it be?
These types of things are loosely defined in the code instead (with comments and reasoning) instead and within src/README.md - this document gives a more practical view on how sansan is organized, what files do what, where things are, why things do x instead of y, etc.
This table summarizes the audio-specific libraries used by sansan and their purpose.
| Dependency | Owner | Purpose |
|---|---|---|
audio_thread_priority |
Mozilla | Real-time audio thread promotion |
cubeb |
Mozilla | Audio device output |
cpal |
RustAudio | Audio device output |
souvlaki |
Sinono3 | OS media control interface |
symphonia |
Pdeljanov | Audio demuxing/decoding/metadata |
rubato |
HEnquist | Audio resampling |
Only 64-bit targets (x86_64, ARM64, etc) are supported.
32-bit targets may work but are not tested on.
- Windows (WASAPI)
- macOS (CoreAudio)
- Linux (PulseAudio)
sansan uses symphonia for audio decoding & metadata.
The supported audio codecs are:
AAC-LCADPCMALACFLACMP1/MP2/MP3VorbisOpusWavPack
The supported audio metadata formats are:
ID3v1ID3v2ISO/MP4RIFFVorbis comment(FLAC & OGG)
The Minimum Supported Rust Version is 1.70.0.
sansan is licensed under the MIT License.
As of v0.0.0, sansan's dependency tree includes the following licenses:
Apache-2.0BSD-2-ClauseBSD-3-ClauseISCMITMPL-2.0Unicode-DFS-2016