PHONOTENSOR / GUIDE / v0.2.2

Files, recording & playback

Bring audio into Python and take the result back out.

Read and write audio files

FileIO.read() returns an AudioTensor with the file’s sample rate and channel count. FileIO.write() supports WAV, FLAC, and OGG through soundfile, plus optional MP3 support. Encoding and subtype availability depend on the installed codecs.

Python

from phonotensor import FileIO, ops

# Run the quickstart first to create tone.wav.
audio = FileIO.read("tone.wav")
quieter = ops.gain(audio, db=-6.0)
FileIO.write(quieter, "output/quiet.wav", subtype="PCM_16")
print(FileIO.supported_formats())

Optional MP3 support

Install the mp3 extra and install FFmpeg separately on your system, with ffmpeg available on PATH. The Python extra alone does not install that executable. MP3 export converts samples to clipped 16-bit PCM before encoding.

Shell

python -m pip install "phonotensor[mp3]==0.2.2"
ffmpeg -version

supported_formats() checks for pydub, not the FFmpeg executable. A listed mp3 format does not guarantee that the system codec is ready.

Record from a microphone

MicrophoneSource checks permissions during construction. record() is synchronous and closes the stream when finished. Run this locally on a machine with an input device and grant microphone access to your terminal or Python app.

Python

from phonotensor import MicrophoneSource, FileIO

mic = MicrophoneSource(sample_rate=44100, channels=1)
print(mic.list_devices())
audio = mic.record(duration=3.0)
FileIO.write(audio, "recording.wav")

# Alternative: stop after a quiet interval, up to 30 seconds.
# audio = mic.record_until_silence(
#     threshold=0.01, silence_duration=1.0, max_duration=30.0
# )

The silence threshold is a linear RMS amplitude, not decibels. The captured result includes the silence used to decide when to stop.

Play an AudioTensor

AudioPlayer uses the default output device unless a device name or index is supplied. Keep initial playback levels low and test on your local audio setup.

Python

from phonotensor import AudioPlayer, ops

preview = ops.sine(440, duration=0.5, amplitude=0.1)
AudioPlayer().play(preview)

In 0.2.2, play(blocking=False) still runs synchronously: the parameter is present but not implemented. play_numpy() infers channels from the data; its channels argument is not used.

Exchange samples as JSON or CSV

TextIO JSON includes sample-rate metadata. CSV contains sample columns, so supply the original sample rate when reading. CSV readers expect a header by default.

Python

from phonotensor import TextIO, fmt, ops

audio = ops.sine(440, duration=0.1, amplitude=0.2)
TextIO.write_json(audio, "samples.json")
restored = TextIO.read_json("samples.json")
TextIO.write_csv(audio, "samples.csv")
from_csv = TextIO.read_csv("samples.csv", sample_rate=44100)
print(fmt.summary(restored))

View source on GitHub ↗Next: Signal processing →