Speaker and Amplifier

# labs/audio_out.py
"""Sound out: tone synthesis, level checks, and WAV playback for her voice."""
import numpy as np

SAMPLE_RATE = 44_100     # Hz — the tone's own rate; a WAV file brings its own
TONE_FREQ = 440.0        # Hz — concert A, easy to hear and easy to check
TONE_DURATION = 1.0      # seconds
FADE_SECONDS = 0.010     # seconds of ramp at each end


def make_sine_tone(freq: float = TONE_FREQ,
                   duration: float = TONE_DURATION,
                   sample_rate: int = SAMPLE_RATE) -> np.ndarray:
    """A mono sine wave as float32 in [-1.0, 1.0]. Touches no hardware."""
    t = np.linspace(0.0, duration, int(sample_rate * duration), endpoint=False)
    return np.sin(2.0 * np.pi * freq * t).astype(np.float32)


if __name__ == "__main__":
    tone = make_sine_tone()
    print(f"samples: {tone.shape[0]}  dtype: {tone.dtype}  ndim: {tone.ndim}")
    print(f"range: {tone.min():.3f} to {tone.max():.3f}")
    print(f"{tone.shape[0]} samples at {SAMPLE_RATE} Hz = {tone.shape[0] / SAMPLE_RATE:.2f} s")

$ uv run python -m labs.audio_out
samples: 44100  dtype: float32  ndim: 1
range: -1.000 to 1.000
44100 samples at 44100 Hz = 1.00 s

Four properties of that array are the entire contract with the output device, and all four are visible here with no hardware attached. The dtype says how each number is encoded, and float32 in the range ±1.0 is what the playback layer expects; the int16 samples chapter 3 wrote into the WAV header are the same waveform in a different currency, and the file reader will convert on the way in. The count of samples means nothing on its own: 44100 of them is one second at 44100 Hz and half a second at 88200 Hz, so duration and pitch both live in a rate that travels beside the array and is never stored in it. And ndim is 1, which is what mono means. Print these three lines before you connect a speaker and the silent failures lose most of their hiding places.

endpoint=False is the small correctness detail. With the endpoint included, linspace would fit 44100 samples across the closed interval from 0 to 1 second, spacing them very slightly wide and duplicating the phase of the first sample at the end. The tone would still sound like an A. It would click at the seam if you ever looped it.

# labs/audio_out.py — added below make_sine_tone


def apply_fades(wave: np.ndarray,
                sample_rate: int = SAMPLE_RATE,
                seconds: float = FADE_SECONDS) -> np.ndarray:
    """Ramp the first and last `seconds` out of and back into silence."""
    n = min(int(sample_rate * seconds), wave.shape[0] // 2)
    wave[:n] *= np.linspace(0.0, 1.0, n, dtype=np.float32)
    wave[-n:] *= np.linspace(1.0, 0.0, n, dtype=np.float32)
    return wave


def scale_volume(wave: np.ndarray, volume: float) -> np.ndarray:
    """Multiply by a volume the caller cannot push past full scale."""
    return wave * np.float32(min(max(volume, 0.0), 1.0))


if __name__ == "__main__":
    n = int(SAMPLE_RATE * FADE_SECONDS)
    faded = scale_volume(apply_fades(make_sine_tone()), 0.7)
    print(f"fade window: {n} samples ({FADE_SECONDS * 1000:.1f} ms at {SAMPLE_RATE} Hz)")
    print(f"sample     0: {faded[0]:.5f}   silence")
    print(f"sample   220: {faded[220]:.5f}   halfway up the ramp")
    print(f"peak at volume 0.70: {float(np.abs(faded).max()):.3f}")
    hot = scale_volume(apply_fades(make_sine_tone()), 5.0)
    print(f"peak at volume 5.00: {float(np.abs(hot).max()):.3f}   volume clamped to 1.0")

$ uv run python -m labs.audio_out
fade window: 441 samples (10.0 ms at 44100 Hz)
sample     0: 0.00000   silence
sample   220: 0.32932   halfway up the ramp
peak at volume 0.70: 0.700
peak at volume 5.00: 1.000   volume clamped to 1.0

A waveform that begins at full amplitude asks the cone to jump from rest to its excursion limit between one sample and the next, in 23 microseconds. That step is not part of the tone; it is a burst of everything, and it arrives as a click at the start of every line she speaks. Ten milliseconds of ramp spreads the arrival across 441 samples and the click disappears. The same ramp at the end covers the amplifier's own switch-off, which has its own thump.

The clamp lives inside scale_volume for the reason chapter 65 put the clamp inside the one private method the eye controller used: the callers multiply, and one of them will eventually be a config file, an over-eager slider, or a language model that decided 5.0 was a reasonable volume. Clamping the multiplier rather than the output is the deliberate part. Clamping the samples afterwards would let a volume of 5.0 through and then flatten every peak it produced, which is precisely the distortion the rest of this chapter is about avoiding.

# labs/audio_out.py — added below scale_volume


def peak_headroom_db(wave: np.ndarray) -> float:
    """Decibels between this signal's loudest sample and full scale."""
    peak = float(np.abs(wave).max())
    if peak == 0.0:
        return float("inf")
    return float(20.0 * np.log10(1.0 / peak))


def count_clipped(wave: np.ndarray, limit: float = 0.999) -> int:
    """Samples at or past full scale: the ones the converter cannot render."""
    return int(np.count_nonzero(np.abs(wave) >= limit))


def report(name: str, wave: np.ndarray) -> None:
    print(f"{name:<22} peak {float(np.abs(wave).max()):.3f}  "
          f"headroom {peak_headroom_db(wave):5.2f} dB  clipped {count_clipped(wave)}")


if __name__ == "__main__":
    report("tone, volume 0.70", scale_volume(apply_fades(make_sine_tone()), 0.7))
    report("tone, volume 1.00", scale_volume(apply_fades(make_sine_tone()), 5.0))
    report("tone, driven 1.4x", np.clip(make_sine_tone() * np.float32(1.4), -1.0, 1.0))

$ uv run python -m labs.audio_out
tone, volume 0.70      peak 0.700  headroom  3.10 dB  clipped 0
tone, volume 1.00      peak 1.000  headroom  0.00 dB  clipped 1216
tone, driven 1.4x      peak 1.000  headroom  0.00 dB  clipped 21800

Decibels are the units everyone else in audio already speaks, and the conversion is one line: a level ratio in decibels is twenty times the base-10 logarithm of the ratio. A peak of 0.7 therefore sits 3.10 dB below full scale, and that number is a budget. Add 3 dB of gain anywhere downstream and the peaks land exactly on the ceiling; add 4 and they go through it.

The bottom two rows have identical peaks and nothing else in common. A clean sine touching full scale reports 1216 samples inside the top thousandth of the range, about 2.8 percent, because a sine spends a real fraction of its cycle near the crest. The same tone multiplied by 1.4 and then limited reports 21800, nearly half of every sample in the file, because the tops have been sawn off flat. The count is a gauge, not a verdict: what you watch is the jump. A voice line that normally reports zero and suddenly reports thousands has been pushed into a ceiling somewhere upstream.

# labs/audio_out.py — added below report
import sounddevice as sd
import soundfile as sf

OUTPUT_MATCH = "hifiberry"   # a substring of the device name, never an index


def find_output(match: str = OUTPUT_MATCH) -> int:
    """Resolve the amplifier by name, fresh on every run."""
    for index, dev in enumerate(sd.query_devices()):
        if dev["max_output_channels"] > 0 and match.lower() in dev["name"].lower():
            print(f"output device {index}: {dev['name']}")
            return index
    raise RuntimeError(f"no output device whose name contains {match!r}")


def play(wave: np.ndarray, sample_rate: int, device: int | None = None) -> None:
    """Hand the array over, then wait for the buffer to drain."""
    sd.play(wave, samplerate=sample_rate, device=device)
    sd.wait()


def play_wav(path: str, volume: float = 0.7, device: int | None = None) -> None:
    """Play one of her lines, reporting the levels before any sound comes out."""
    data, rate = sf.read(path, dtype="float32")
    channels = 1 if data.ndim == 1 else data.shape[1]
    scaled = scale_volume(data, volume)
    print(f"{path}: {rate} Hz  {channels} ch  {data.shape[0] / rate:.2f} s")
    print(f"  source peak {float(np.abs(data).max()):.3f} "
          f"(headroom {peak_headroom_db(data):.2f} dB)   "
          f"after volume {volume:.2f}: peak {float(np.abs(scaled).max()):.3f}, "
          f"clipped {count_clipped(scaled)}")
    play(scaled, rate, device)
    print("playback complete.")


if __name__ == "__main__":
    device = find_output()
    play(scale_volume(apply_fades(make_sine_tone()), 0.7), SAMPLE_RATE, device)
    play_wav("glados/data/voice/line.wav", volume=0.7, device=device)

$ uv run python -m labs.audio_out   # measured on the bench — yours will vary
output device 2: snd_rpi_hifiberry_dac: - (hw:2,0)
glados/data/voice/line.wav: 22050 Hz  1 ch  2.71 s
  source peak 0.951 (headroom 0.44 dB)   after volume 0.70: peak 0.666, clipped 0
playback complete.

Two things here are inherited rather than invented. The device is looked up by a substring of its name for the reason chapter 67 gave when it did the same to the microphone: an index is the order the kernel noticed things in, and adding one USB device renumbers it. The rate comes back from sf.read beside the samples and is passed straight through to sd.play, so the file's own 22050 Hz follows its own array and never gets confused with the tone's 44100.

The ndim branch is not defensive padding. soundfile returns a flat 1-D array for a mono file and a 2-D array of frames by channels for a stereo one, so data.shape[1] reads the channel count correctly on a stereo music file and raises IndexError: tuple index out of range on every one of her lines, because Piper writes mono. Asking ndim first costs one comparison and makes both paths work. Note also what sd.wait is for: sd.play hands the buffer to PortAudio and returns immediately, so without the wait a short script exits while the line is still playing and you hear the first syllable and nothing else.