Ears

# labs/record_audio.py
import sounddevice as sd

SAMPLE_RATE = 16000
CHANNELS = 1
DURATION = 5

print(f"Recording for {DURATION} seconds... Speak now.")
audio = sd.rec(
    int(DURATION * SAMPLE_RATE),
    samplerate=SAMPLE_RATE,
    channels=CHANNELS,
    dtype="float32",
)
sd.wait()
print(f"Captured array: shape={audio.shape}, dtype={audio.dtype}")

$ uv run python labs/record_audio.py
Recording for 5 seconds... Speak now.
Captured array: shape=(80000, 1), dtype=float32

uv add soundfile first (sounddevice and numpy arrived in chapter 3). Two things to notice. sd.rec() returns immediately, handing you an array the audio engine will fill over the next five seconds on a background thread; sd.wait() is what blocks until it is actually full. And the reported dimensions are your first verification: 80,000 frames is exactly DURATION * SAMPLE_RATE, one column because mono. When the arithmetic and the report agree, the capture path is wired the way you think it is.

import soundfile as sf

OUTPUT = "glados/data/captured_audio.wav"
sf.write(OUTPUT, audio, SAMPLE_RATE)
data, samplerate = sf.read(OUTPUT)
print(f"Saved {OUTPUT}: {len(data)} frames at {samplerate} Hz")

$ uv run python labs/record_audio.py
Recording for 5 seconds... Speak now.
Saved glados/data/captured_audio.wav: 80000 frames at 16000 Hz

Last chapter you built a WAV header by hand so you would know what lives in one; from now on soundfile writes it, taking the array and the rate and handling the format. The immediate read-back is a cheap round-trip test: 80,000 frames out means the file holds what the buffer held. Cheap tests you always run beat thorough tests you sometimes run.

import numpy as np

SILENCE_THRESHOLD = 0.01

rms = float(np.sqrt(np.mean(audio ** 2)))
print(f"Signal level (RMS): {rms:.4f}")
if rms < SILENCE_THRESHOLD:
    print("WARNING: near silence -- is this the right input device?")

$ uv run python labs/record_audio.py   # mic muted on purpose
Recording for 5 seconds... Speak now.
Signal level (RMS): 0.0060
WARNING: near silence -- is this the right input device?
Saved to glados/data/captured_audio.wav

RMS, root-mean-square, is the average energy of the signal: square every sample, average, take the root. One number that answers "did the microphone hear anything?" Silence sits near zero; normal speech lands well above 0.01. The run shown was captured with the mic muted on purpose, so the guard fired; speak normally and you should see something in the 0.02–0.2 region, with the exact figure depending on your microphone and your room. This single check catches the two most common capture failures, wrong device and muted input, before they poison everything downstream.

# labs/record_audio.py — full file
import numpy as np
import sounddevice as sd
import soundfile as sf

SAMPLE_RATE = 16000
CHANNELS = 1
DURATION = 5
OUTPUT = "glados/data/captured_audio.wav"
SILENCE_THRESHOLD = 0.01

def record(duration: int) -> np.ndarray:
    print(f"Recording for {duration} seconds... Speak now.")
    audio = sd.rec(
        int(duration * SAMPLE_RATE),
        samplerate=SAMPLE_RATE,
        channels=CHANNELS,
        dtype="float32",
    )
    sd.wait()
    return audio

def rms_level(audio: np.ndarray) -> float:
    return float(np.sqrt(np.mean(audio ** 2)))

def main() -> None:
    audio = record(DURATION)
    rms = rms_level(audio)
    print(f"Signal level (RMS): {rms:.4f}")
    if rms < SILENCE_THRESHOLD:
        print("WARNING: near silence -- is this the right input device?")
    sf.write(OUTPUT, audio, SAMPLE_RATE)
    print(f"Saved to {OUTPUT}")
    print("Playing back...")
    data, samplerate = sf.read(OUTPUT)
    sd.play(data, samplerate)
    sd.wait()
    print("Done.")

if __name__ == "__main__":
    main()

$ uv run python labs/record_audio.py
Recording for 5 seconds... Speak now.
Signal level (RMS): 0.0731
Saved to glados/data/captured_audio.wav
Playing back...
Done.

The chapter-2 conventions, applied under pressure: record returns the buffer, rms_level returns the number, main owns every print and the playback. Chapter 5 imports record; chapter 10 imports both. The playback at the end is the human check on top of the numeric one — you hear your own voice, or you find out now that something upstream lied.