cpal-python

This repo provides a small Python binding layer for the Rust cpal audio I/O library.

Build / install (source)

Requires Rust toolchain + Python 3.8+.

pip install maturin
pip install .

Quick usage

from typing import Optional

import cpal

host = cpal.default_host()
print(host.id(), cpal.available_hosts())

device = host.default_output_device()
cfg = device.default_output_config()

def out_cb(expected_bytes: int, info: dict) -> Optional[bytes]:
    # Return None to output silence (equilibrium is handled per sample_format).
    return None

stream = device.build_output_stream(cfg, out_cb)
stream.play()

Stream callbacks

• Output callback: callback(expected_bytes: int, info: dict) -> bytes/bytearray or None
  • info["sample_format"] is a string like "f32", "i16", "u16", etc.
  • Return None for silence, or return raw sample bytes (interleaved channels).
• Input callback: callback(data: bytes, info: dict) -> None

config can be a dict (e.g. from device.default_output_config()), or a cpal.StreamConfig dataclass.

If a Python callback raises, the stream keeps running and you can query the last error via:

err = stream.take_last_callback_error()

Optional backends / features

The wrapper forwards CPAL cargo features:

• asio
• jack
• custom
• wasm-bindgen
• audioworklet

With maturin, you can build with features like:

maturin develop --features asio