sound_rs is a fast, Rust-powered audio library for Python that I built and maintain β decoding with symphonia, resampling with rubato, output through cpal.
Documentation: neksand.github.io/sound_rs β guides,
API reference, the soundrs command and the benchmark methodology.
Latest release: 0.8.0 β adds
Opus in Ogg and WebM on pure-Rust Symphonia 0.6, on top of probe(), MCP, the streaming
Decoder and formats. Guides for coding agents:
llms.txt and AGENTS.md.
- Formats: WAV (including tested 24-bit PCM), MP3, FLAC, OGG/Vorbis, AAC and ALAC in M4A/MP4, Opus in Ogg/WebM, AIFF and CAF; support depends on the codec and container, not just the file extension
- Streaming playback: incremental decoding into a bounded one-second playback ring; the full file is not retained in memory, while decoder/filter/process overhead is additional
Player: one output stream stays open βplay_file,play_array,pause,resume,seek,stop,volume,position,duration,paused- Decode to NumPy:
load(path, sample_rate=, mono=, offset=, duration=)β resample to 16 kHz mono in one call, or decode only a window - Streaming decoder:
Decoder(path, block_frames=, sample_rate=, mono=)iterates fixed-size float32 blocks with bounded memory and retained resampler state - Parallel decode:
load_many(paths, sample_rate=, mono=, on_error="skip")uses every core, releases the GIL and can leaveNonefor corrupt files - Recording:
Recorder()captures from the microphone;record_to(path, seconds)saves a take in one call. A bounded callback ring feeds a collector thread; overflow and device faults raise an error instead of returning an incomplete successful take - Writing:
write(path, audio, rate, subtype=)saves WAV as PCM16, PCM24 or float32;write_bytesreturns the same WAV without touching disk. Encoding releases the GIL - Queues and live input:
Player.enqueue(path)chains tracks;begin_feed/feedpush samples from Python with backpressure. Queueing requires a file source; feed timeouts measure lack of progress, andwait()includes the final audio drain - Gapless metadata: encoder delay/padding are trimmed where available. All MP3 paths use Symphonia; AAC can retain less than one codec frame of tail padding
- Metadata:
get_audio_inforeturns the(rate, channels, duration)tuple;probereturns a dict with codec, bit depth, frames and optional fields - Resampling: rubato's FFT resampler with a proper anti-aliasing filter and streaming EOF drain that preserves the converted frame count and filter tail
- Device-native output: the stream opens in whatever sample format the device wants (f32, f64, i16, i32, u8, u16)
- Errors: library failures raise
sound_rs.SoundRsErrorwith a stable.code(io,format,device,stalled,unsupported,usage) - Tested behavior: malformed-input mutation tests, quantized fixture hashes and MP3 length/level checks, ring-starvation reporting. The full list is on the docs site.
- No external decoder: MP3, FLAC, OGG, AAC, Opus, ALAC, AIFF, CAF and WAV decoders are inside the wheel. Linux wheels bundle the ALSA runtime; source builds need ALSA development headers. NumPy is required for array APIs
- CLI and MCP:
soundrs info --json,soundrs convert, andsoundrs mcpfor agent tool calls without opening an audio device - Typed: ships
sound_rs.pyiandpy.typed, so editors autocomplete everything
pip install sound_rsWheels are built with the stable ABI (abi3-py310): one per platform β Linux
x86_64 and aarch64 (glibc), Linux x86_64 (musl), Windows amd64, macOS arm64 and
Intel β each covering Python 3.10 and newer. Other platforms build from source.
For loading, writing, array playback and recording arrays, use pip install 'sound_rs[numpy]'.
Python argument conversion may raise TypeError or OverflowError; float64 arrays are rejected.
Installing the package also installs soundrs, so you can check the setup and read the docs
without opening Python:
soundrs --help # commands and the documentation link
soundrs devices # output devices, default marked with *
soundrs info a.flac # rate, channels, duration; decodes if the header is incomplete
soundrs info a.flac --json
soundrs convert a.mp3 a.wav --subtype pcm24
soundrs mcp # MCP stdio server for agents
soundrs play a.flac --volume 0.5
soundrs docs # prints https://neksand.github.io/sound_rs/Exit codes: 0 success, 1 runtime failure, 2 bad usage.
File-path arguments accept str or os.PathLike (pathlib.Path) throughout, including
Player.play_file, Player.enqueue and Recorder.record_to.
import sound_rs
sound_rs.play_audio("sound.wav") # blocks, GIL released
sound_rs.play_audio("sound.mp3", device="MacBook Pro Speakers")import sound_rs
with sound_rs.Player() as player:
player.play_file("music.flac") # returns immediately, streams from disk
player.volume = 0.7
player.seek(42.0)
player.pause()
player.resume()
print(player.position, player.duration)
player.wait() # block until it ends
sound_rs.list_devices() # [(0, "MacBook Pro Speakers", True), ...]Create, use and destroy each Player or Recorder on the same thread. Separate threads
can own separate instances. Playback waits release the GIL; preparation and teardown can
still run while holding it.
import sound_rs
with sound_rs.Recorder() as recorder:
audio, rate = recorder.record(5.0) # float32, (frames, channels)import sound_rs
audio, rate = sound_rs.load("take.flac") # (frames, channels)
sound_rs.write("take.wav", audio, rate, subtype="pcm24")
raw = sound_rs.write_bytes(audio, rate) # complete WAV as bytes
with sound_rs.Recorder() as recorder:
recorder.record_to("take.wav", 5.0) # record and saveArrays use (frames, channels) β the layout load returns β so a load/write round-trip
needs no transpose.
import numpy as np
import sound_rs
with sound_rs.Player() as player:
player.play_file("a.flac")
player.enqueue("b.mp3") # plays next, own rate and layout
player.wait()
player = sound_rs.Player()
player.begin_feed(48000)
player.feed(np.zeros(4800, dtype=np.float32)) # blocks when the buffer is full
player.end_feed()
player.wait()sample_rate, channels, duration = sound_rs.get_audio_info("music.mp3") # header when sufficient
info = sound_rs.probe("music.mp3") # dict incl. codec/bit depth
audio, rate = sound_rs.load("music.flac") # (frames, channels) float32
audio, rate = sound_rs.load("music.flac", sample_rate=16000, mono=True) # dataset shape
pairs = sound_rs.load_many(["a.flac", "b.flac", "c.flac"]) # parallel
pairs = sound_rs.load_many(paths, on_error="skip") # None for corrupt files
with sound_rs.Decoder("long.flac", block_frames=4800, sample_rate=16000, mono=True) as d:
for block in d:
process(block) # bounded memory, (frames, 1) float32import numpy as np
rate = 44100
t = np.linspace(0, 2.0, rate * 2, endpoint=False, dtype=np.float32)
sound_rs.play_array(np.sin(2 * np.pi * 440 * t), rate) # mono, 1D
sound_rs.play_array(np.stack([left, right]), rate) # 2D, channels first
sound_rs.play_sine_wave(440.0, 1.0, 44100)Latest local run: 2026-11-12 on Apple M5 Pro, Python 3.14, against soundfile, sounddevice, miniaudio, librosa and pydub β full report.
Every measurement runs in its own process: peak RSS is process-wide, so timing and memory cannot share one. Median and p95 over repeated runs, competitors run side by side on the same files.
python bench/run.py # sound_rs only
python bench/run.py --compare # + soundfile / sounddevice / miniaudio / librosa / pydub when installed
python bench/run.py --reps 9Historical 0.3.0 measurements: Apple M5 Pro, macOS 26.6.2, Python 3.14.7, release
build (lto = "fat", opt-level = 3). Competitors: libsndfile 1.2
(soundfile 0.14), PortAudio (sounddevice). Corpus: 3 s and 10 min stereo
44.1 kHz, generated by the harness.
The tables below are historical measurements, not performance guarantees for a current device. The 0.3.0 report records the original run; the current engineering report separates newly executed headless measurements from device tests that were not rerun.
Historical scoreboard:
| axis | sound_rs | best competitor | ratio |
|---|---|---|---|
| import | 1.1 ms | 31.8 ms (soundfile) | 29Γ |
| metadata (60 s file) | 1.2 ms | 31.7 ms (soundfile) | 26Γ |
| decode WAV | 130 ms | 157 ms | 1.2Γ |
| decode FLAC | 265 ms | 455 ms | 1.7Γ |
| decode MP3 | 241 ms | 268 ms | 1.1Γ |
| decode AAC | 349 ms | not supported | β |
| time to first sound (10 min) | 11 ms | 302 ms | 27Γ |
| peak RAM (10 min file) | 43 MB | 255 MB | 6Γ |
| playback overhead | 30 ms | 241 ms | 8Γ |
| batch decode (2 files) | 177 ms | 299 ms | 1.7Γ |
Detailed original timings and validation are retained in the linked historical report.
What the numbers do not hide:
- MP3 alignment: the 0.3.0 table above used minimp3 and had a 47-sample offset. The current Symphonia path aligns with ffmpeg at lag 0 on the committed fixture; the historical timings remain unchanged.
- WAV decode is a memcpy race with libsndfile; the gap there is small by nature, the real wins are FLAC, metadata, memory and latency.
- AAC decoding is slower than everything else β it is a newer, less tuned decoder β but libsndfile cannot read AAC at all.
| Step | Feature | Description |
|---|---|---|
| β 1 | Playback + formats | WAV, MP3, FLAC, OGG, M4A/AAC/ALAC, AIFF, CAF, 24-bit |
| β 2 | NumPy integration | 1D/2D arrays, load, load_many |
| β 3 | Player |
Persistent stream: pause, seek, volume, position |
| β 4 | Streaming decode | Bounded playback ring, incremental file decoding |
| β 5 | Device selection | list_devices, list_input_devices, device= |
| β 6 | Recording | Recorder: microphone to float32 array |
| β 7 | Queues and live input | enqueue, begin_feed/feed |
| β 8 | Datasets | load(..., sample_rate=16000, mono=True), parallel load_many |
| β 9 | Writing files | write, Recorder.record_to, PCM16/PCM24/float32 WAV |
| Under investigation | Hot-swap on disconnect | Requires device-backed recovery and cancellation tests on each OS |
| Planned | Editing and level analysis | Frame-first slice/join/gain/fade/normalize/RMS/peak with numerical semantics |
| β 10 | Continuous fed resampling | Filter state retained across feed blocks; end_feed flushes the tail with exact frame counts |
| Planned | Incremental disk recording | Bounded memory and correct WAV finalization on errors/cancel |
| Under investigation | FFT/STFT, filters and synthesis | Independent numerical references and documented axes/latency |
The implementation plan gives acceptance criteria. The engineering audit and PR roadmap distinguish current capabilities, proposed fixes and deferred work.
cargo test # decode, gapless, seek, fuzzing, properties, player
cargo clippy --all-targets -- -D warnings
maturin develop --release # build into your venv
python tests/smoke.py # end-to-end decode + API checks
python tests/test_validation.py # invalid inputs, WAV boundaries, NumPy layouts, GIL
SOUND_RS_PLAY=1 python tests/smoke.py # also plays (needs an audio device)
python tests/decode_regression.py # PCM hashes; must not change
python docs/check_api.py # every public name is documented
python docs/check_site.py # links, anchors, search, sitemap, Markdown and llms
python -m unittest discover -s tests -p 'test_*.py'
python3 docs/_build.py # docs site, llms.txt and .md pages
python bench/run.py --compare --report bench/REPORT.md
python bench/run.py --compare --no-audio # reproducible device-free subset- π¦ Rust β performance and safety
- π PyO3 β Python bridge
- π§° Maturin β building and publishing
- π cpal, symphonia, rubato β output, decoding, resampling
Nurassyl Mussainov Kazakhstan π°πΏ Python / Rust Developer
π GitHub: Neksand π¦ PyPI: sound_rs
Licensed under the MIT License β free for personal and commercial use.