I/O¶

Read and write WAV (8/16/24/32-bit PCM) and FLAC (16/24-bit) files. WAV uses the Python stdlib wave module; FLAC uses the CHOC codec.

Usage examples¶

Read and write files¶

from nanodsp import io

# Auto-detect format by extension
buf = io.read("input.wav")
buf = io.read("input.flac")

io.write("output.wav", buf)                  # 16-bit default
io.write("output.wav", buf, bit_depth=24)    # 24-bit WAV
io.write("output.flac", buf, bit_depth=24)   # 24-bit FLAC

Format-specific functions¶

buf = io.read_wav("file.wav")
io.write_wav("out.wav", buf, bit_depth=24)

buf = io.read_flac("file.flac")
io.write_flac("out.flac", buf, bit_depth=16)

Byte-level I/O (for pipes and streaming)¶

# Parse WAV from raw bytes (e.g., from stdin)
import sys
raw = sys.stdin.buffer.read()
buf = io.read_wav_bytes(raw)

# Serialize to WAV bytes (e.g., for stdout)
out_bytes = io.write_wav_bytes(buf, bit_depth=16)
sys.stdout.buffer.write(out_bytes)

API reference¶

io ¶

Audio file I/O for AudioBuffer.

Supported formats (detected by extension): .wav -- 8/16/24/32-bit PCM read, 16/24-bit PCM write (stdlib wave) .flac -- 16/24-bit read/write (CHOC FLAC codec, zero external dependencies)

read ¶

read(path: str | Path) -> AudioBuffer

Read an audio file and return an AudioBuffer.

Format is detected by file extension (.wav, .flac).

write ¶

write(
    path: str | Path, buf: AudioBuffer, bit_depth: int = 16
) -> None

Write an AudioBuffer to an audio file.

Format is detected by file extension (.wav, .flac).

PARAMETER	DESCRIPTION
`path`	Output file path. TYPE: `str or Path`
`buf`	Audio data to write. TYPE: `AudioBuffer`
`bit_depth`	Output bit depth: 16 or 24. TYPE: `int` DEFAULT: `16`

read_wav ¶

read_wav(path: str | Path) -> AudioBuffer

Read a WAV file and return an AudioBuffer.

Supports 8-bit unsigned, 16-bit signed, 24-bit signed, and 32-bit signed PCM. Output is float32 normalized to [-1, 1].

write_wav ¶

write_wav(
    path: str | Path, buf: AudioBuffer, bit_depth: int = 16
) -> None

Write an AudioBuffer to a WAV file.

PARAMETER	DESCRIPTION
`path`	Output file path. TYPE: `str or Path`
`buf`	Audio data to write. TYPE: `AudioBuffer`
`bit_depth`	Output bit depth: 16 or 24. TYPE: `int` DEFAULT: `16`

read_wav_bytes ¶

read_wav_bytes(data: bytes) -> AudioBuffer

Read WAV data from raw bytes and return an AudioBuffer.

Supports 8/16/24/32-bit PCM. Output is float32 normalized to [-1, 1].

write_wav_bytes ¶

write_wav_bytes(
    buf: AudioBuffer, bit_depth: int = 16
) -> bytes

Serialize an AudioBuffer to WAV bytes.

PARAMETER	DESCRIPTION
`buf`	Audio data to write. TYPE: `AudioBuffer`
`bit_depth`	Output bit depth: 16 or 24. TYPE: `int` DEFAULT: `16`

RETURNS	DESCRIPTION
`bytes`	WAV file content.

read_flac ¶

read_flac(path: str | Path) -> AudioBuffer

Read a FLAC file and return an AudioBuffer.

Output is float32 normalized to [-1, 1].

write_flac ¶

write_flac(
    path: str | Path, buf: AudioBuffer, bit_depth: int = 16
) -> None

Write an AudioBuffer to a FLAC file.

PARAMETER	DESCRIPTION
`path`	Output file path. TYPE: `str or Path`
`buf`	Audio data to write. TYPE: `AudioBuffer`
`bit_depth`	Output bit depth: 16 or 24. TYPE: `int` DEFAULT: `16`