Skip to content

hinto-janai/sansan

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CI crates.io docs.rs

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 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.

Example

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
// TODO

Design

sansan'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.

Audio Dependencies

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

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 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.

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