music.read_audio¶

music.read_audio(filename: str, return_sample_rate: Literal[False] = False) → NDArray[float64][source]¶

music.read_audio(filename: str, return_sample_rate: Literal[True]) → tuple[NDArray[float64], int]

Read an audio file and return an array of its values.

Parameters:

filenamestr: The path to read. WAV and FLAC are understood; the container is whatever the file says it is, not what the extension claims.
return_sample_ratebool: Return the file’s sample rate as well, as (samples, rate).

Returns:

NDArray: The samples in [-1, 1], mono as (nsamples,) and stereo as (2, nsamples). Integer PCM is divided by its own full scale; a float WAV declares none, so it is scaled by its own peak.
int: The file’s sample rate, only with return_sample_rate=True.

Raises:

ValueError: If the file’s encoding is one this package cannot normalize – anything outside READABLE_SUBTYPES. libsndfile will decode ADPCM and companded formats happily, but they have no full scale the normalization is defined against, so being decodable is not the same as being supported.

Warns:

UserWarning: If the file’s rate is not music.get_sample_rate()’s and was not asked for. Every routine that is not told otherwise works at that rate, so a 48 kHz file read without its rate and written back came out at 44.1 kHz, a semitone and a half flat and 9 % long, and nothing said so. Ask for the rate, or set it, and the warning goes.

Examples

>>> write_audio(note(freq=440, duration=0.5), "tone.flac")
>>> read_audio("tone.flac").shape      # any format libsndfile reads
(22050,)
>>> samples, rate = read_audio("tone.flac", return_sample_rate=True)
>>> rate
44100