https://github.com/hinto-janai/sansan
Real-time music engine (WIP)
https://github.com/hinto-janai/sansan
audio audio-player audio-processing engine linux macos media metadata music real-time rust windows
Last synced: 12 months ago
JSON representation
Real-time music engine (WIP)
- Host: GitHub
- URL: https://github.com/hinto-janai/sansan
- Owner: hinto-janai
- License: mit
- Created: 2023-03-27T13:48:00.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-31T17:31:55.000Z (over 2 years ago)
- Last Synced: 2025-06-27T18:18:50.234Z (12 months ago)
- Topics: audio, audio-player, audio-processing, engine, linux, macos, media, metadata, music, real-time, rust, windows
- Language: Rust
- Homepage: https://sansan.cat
- Size: 8.05 MB
- Stars: 13
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
 [](https://crates.io/crates/sansan) [](https://docs.rs/sansan)
## About
`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/Vorbis` tags)
- 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.
## Documentation
The book at [`https://sansan.cat`](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`](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.
## Example
For more example usage of `sansan`, see [`examples/`](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
```rust
// TODO
```
## Design
`sansan`'s abstract design is documented in [`DESIGN.md`](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`](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.
## Audio Dependencies
This table summarizes the **audio-specific** libraries used by `sansan` and their purpose.
| Dependency | Owner | Purpose |
|-------------------------|-------------------------------------------------------------|---------|
| `audio_thread_priority` | [Mozilla](https://github.com/mozilla/audio_thread_priority) | Real-time audio thread promotion
| `cubeb` | [Mozilla](https://github.com/mozilla/cubeb-rs) | Audio device output
| `cpal` | [RustAudio](https://github.com/rustaudio/cpal) | Audio device output
| `souvlaki` | [Sinono3](https://github.com/Sinono3/souvlaki) | OS media control interface
| `symphonia` | [Pdeljanov](https://github.com/pdeljanov/Symphonia) | Audio demuxing/decoding/metadata
| `rubato` | [HEnquist](https://github.com/HEnquist/rubato) | Audio resampling
## Supported Targets
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)
## Supported Audio
`sansan` uses [`symphonia`](https://github.com/pdeljanov/Symphonia) for audio decoding & metadata.
The supported audio codecs are:
- `AAC-LC`
- `ADPCM`
- `ALAC`
- `FLAC`
- `MP1/MP2/MP3`
- `Vorbis`
- `Opus`
- `WavPack`
The supported audio metadata formats are:
- `ID3v1`
- `ID3v2`
- `ISO/MP4`
- `RIFF`
- `Vorbis comment` (FLAC & OGG)
## MSRV
The `Minimum Supported Rust Version` is `1.70.0`.
## License
`sansan` is licensed under the [MIT License](https://github.com/hinto-janai/sansan/blob/main/LICENSE).
As of `v0.0.0`, `sansan`'s dependency tree includes the following licenses:
- `Apache-2.0`
- `BSD-2-Clause`
- `BSD-3-Clause`
- `ISC`
- `MIT`
- `MPL-2.0`
- `Unicode-DFS-2016`