Microphone Array

# labs/mic_setup.py

def find_input_device(devices: list[dict], name_substring: str) -> int | None:
    """Index of the first INPUT device whose name contains the substring, else None."""
    target = name_substring.lower()
    for idx, dev in enumerate(devices):
        if dev["max_input_channels"] > 0 and target in dev["name"].lower():
            return idx
    return None


if __name__ == "__main__":
    # The exact structure sd.query_devices() returns: a sequence of dicts.
    table = [
        {"name": "bcm2835 Headphones", "max_input_channels": 0},
        {"name": "ReSpeaker Playback", "max_input_channels": 0},
        {"name": "ReSpeaker 4 Mic Array (UAC1.0)", "max_input_channels": 6},
        {"name": "USB PnP Sound Device", "max_input_channels": 1},
    ]
    for query in ("respeaker", "usb pnp", "bluetooth"):
        print(f"{query!r:12} -> {find_input_device(table, query)}")

$ uv run python -m labs.mic_setup
'respeaker'  -> 2
'usb pnp'    -> 3
'bluetooth'  -> None

Two decisions are doing all the work here, and neither needed hardware to make. The max_input_channels > 0 test is what stops the search at index 2 instead of index 1, even though both names contain "respeaker": the playback endpoint of the same physical device advertises zero input channels, so it can never be selected by accident. And a miss returns None, an answer the caller can act on, in place of the two alternatives people reach for. Returning 0 hands back a working index that points at the wrong device. Raising immediately takes the decision away from the caller, who may have a fallback in mind.

# labs/mic_setup.py — added above find_input_device
import sounddevice as sd


def list_input_devices() -> list[dict]:
    """Print every input device with index, name, channels and native rate."""
    devices = sd.query_devices()
    print(f"{'Idx':>3}  {'Name':<40}  {'In':>2}  {'Rate':>6}")
    print("-" * 58)
    for idx, dev in enumerate(devices):
        if dev["max_input_channels"] > 0:
            print(f"{idx:>3}  {dev['name']:<40.40}  "
                  f"{dev['max_input_channels']:>2}  "
                  f"{int(dev['default_samplerate']):>6}")
    return devices

$ uv run python -m labs.mic_setup --list   # on the Pi — your table will differ
Idx  Name                                      In    Rate
----------------------------------------------------------
  1  ReSpeaker 4 Mic Array (UAC1.0): USB Audi   6   16000
  3  sysdefault                                128   44100
  5  default                                   128   44100

The function prints and also returns, which looks like two jobs until you notice they have different audiences. The printed table is for you: it is how you discover that "respeaker" is a substring nothing else on this machine claims. The returned list is for the program, and returning the same list you printed means name resolution runs against exactly the table you just looked at, with no second call to query_devices() that might disagree.

Read the last two rows before moving on. sysdefault and default both report 128 input channels at 44,100 Hz, and neither is a microphone. They are ALSA plugin devices that forward to something else, and their advertised numbers are placeholders for "whatever the target turns out to support". Recording from those is how you end up resampling audio you never needed to resample. The array's own row says 6 channels at 16,000 Hz, which is the rate the capture path has wanted since chapter 4.

# labs/mic_setup.py — added below find_input_device
import numpy as np

SAMPLE_RATE = 16_000
CHANNELS = 1
DURATION = 3


def signal_report(audio: np.ndarray) -> tuple[float, float]:
    """Peak and RMS level of a buffer. The float64 cast is load-bearing."""
    wide = audio.astype(np.float64)
    peak = float(np.abs(wide).max())
    rms = float(np.sqrt(np.mean(wide ** 2)))
    return peak, rms


if __name__ == "__main__":
    # A 220 Hz sine at amplitude 0.1 has a known RMS: 0.1 / sqrt(2).
    seconds = np.linspace(0, 3, 3 * SAMPLE_RATE, endpoint=False)
    tone = (0.1 * np.sin(2 * np.pi * 220 * seconds)).astype(np.float32)
    peak, rms = signal_report(tone)
    print(f"peak {peak:.4f}  rms {rms:.4f}  expected rms {0.1 / np.sqrt(2):.4f}")

$ uv run python -m labs.mic_setup
peak 0.1000  rms 0.0707  expected rms 0.0707

Peak and RMS answer different questions and the pipeline needs both. Peak is the largest single sample, so it catches a click, a chair scrape, or a signal already clipping at 1.0 with distortion baked in. RMS squares every sample, averages, and takes the root, so it reports sustained energy, and sustained energy is what "is somebody talking" actually means. The synthetic tone is here because a level meter you cannot check is not a measurement. A sine of amplitude A has an RMS of A divided by the square root of two, always, so an implementation that prints 0.0707 for this input is arithmetically correct before a microphone is ever involved.

# labs/mic_setup.py — the capture path
import argparse
import sys

import soundfile as sf

OUTPUT_FILE = "glados/data/mic_test.wav"
DEAD_MIC_RMS = 0.0005     # below this, the buffer is not a quiet room, it is nothing


def record(device_index: int, seconds: int = DURATION) -> np.ndarray:
    """Capture mono audio at SAMPLE_RATE from one device index."""
    audio = sd.rec(int(seconds * SAMPLE_RATE), samplerate=SAMPLE_RATE,
                   channels=CHANNELS, dtype="float32", device=device_index)
    sd.wait()
    return audio


def resolve(devices: list[dict], name: str) -> int:
    """Name substring to index, or exit with the table already printed above."""
    idx = find_input_device(devices, name)
    if idx is None:
        print(f"No input device matching {name!r}. Pick a substring from the table.")
        sys.exit(1)
    return idx


def main() -> None:
    parser = argparse.ArgumentParser(description="GLaDOS microphone setup")
    parser.add_argument("--list", action="store_true", help="print the input table and stop")
    parser.add_argument("--name", default="respeaker", help="device name substring")
    args = parser.parse_args()

    devices = list_input_devices()
    if args.list:
        return

    idx = resolve(devices, args.name)
    print(f"\nRecording {DURATION}s from index {idx} at {SAMPLE_RATE} Hz mono. Speak now.")
    audio = record(idx)
    sf.write(OUTPUT_FILE, audio, SAMPLE_RATE)
    peak, rms = signal_report(audio)
    verdict = "dead or muted" if rms < DEAD_MIC_RMS else "hearing something"
    print(f"Saved {OUTPUT_FILE}  peak {peak:.4f}  rms {rms:.4f}  ({verdict})")


if __name__ == "__main__":
    main()

$ uv run python -m labs.mic_setup --name respeaker   # measured on the bench — yours will vary
Idx  Name                                      In    Rate
----------------------------------------------------------
  1  ReSpeaker 4 Mic Array (UAC1.0): USB Audi   6   16000
  3  sysdefault                                128   44100
  5  default                                   128   44100

Recording 3s from index 1 at 16000 Hz mono. Speak now.
Saved glados/data/mic_test.wav  peak 0.3120  rms 0.0912  (hearing something)

Notice how low DEAD_MIC_RMS is set. It is not asking "was that loud enough to transcribe", it is asking "did any electrical signal arrive at all", and those are separate questions that want separate numbers. A muted array, an unplugged array, and a capture from an ALSA plugin pointing at nothing all return buffers within a whisker of exact zero, while a quiet room still carries a floor of a couple of thousandths. Setting the dead-mic test at 0.0005 puts it below any real room and above nothing at all, so it fires on a broken cable and stays silent about a quiet one.

The verdict is printed next to the peak and the RMS on purpose. A line that only says "hearing something" is a claim you have to take on faith; the same line carrying 0.3120 and 0.0912 lets you disagree with it. Every boundary between the physical world and her code gets that treatment: report the measurement beside the judgement, and a wrong judgement has nowhere to hide.

# labs/mic_distance.py
import math

import numpy as np

from labs.mic_setup import (SAMPLE_RATE, find_input_device, list_input_devices,
                            record, signal_report)

SILENCE_GATE = 0.005     # the wake-word gate, calibrated at arm's length in a quiet room
REF_METRES = 0.3         # the distance the gate was calibrated at
CAPTURE_SECONDS = 4

POSITIONS = [
    (0.3, "leaning over her"),
    (1.2, "seated at the desk"),
    (2.5, "standing across the room"),
    (4.2, "kitchen doorway"),
]


def free_field_rms(ref_rms: float, metres: float) -> float:
    """Level predicted by distance alone: pressure falls as 1/r in open air."""
    return ref_rms * REF_METRES / metres


def snr_db(signal_rms: float, floor_rms: float) -> float:
    """How far the voice sits above the room, in decibels."""
    return 20.0 * math.log10(signal_rms / floor_rms)


def measure(device_index: int, prompt: str) -> float:
    input(f"{prompt} — press Enter, then read one sentence aloud.")
    _, rms = signal_report(record(device_index, CAPTURE_SECONDS))
    return rms


def main() -> None:
    devices = list_input_devices()
    idx = find_input_device(devices, "respeaker")
    floor = measure(idx, "\nStay silent for the room floor")
    print(f"Room floor, no one speaking: rms {floor:.4f}\n")

    print(f"{'m':>4}  {'position':<26}  {'rms':>7}  {'free-field':>10}  {'SNR dB':>7}  gate")
    ref_rms = None
    for metres, label in POSITIONS:
        rms = measure(idx, f"\nStand at {metres} m ({label})")
        ref_rms = rms if ref_rms is None else ref_rms
        print(f"{metres:>4.1f}  {label:<26}  {rms:>7.4f}  "
              f"{free_field_rms(ref_rms, metres):>10.4f}  "
              f"{snr_db(rms, floor):>7.1f}  {'open' if rms >= SILENCE_GATE else 'SHUT'}")


if __name__ == "__main__":
    main()

$ uv run python -m labs.mic_distance   # measured on the bench — yours will vary
Room floor, no one speaking: rms 0.0021

   m  position                        rms  free-field   SNR dB  gate
 0.3  leaning over her             0.0912      0.0912     32.8  open
 1.2  seated at the desk           0.0310      0.0228     23.4  open
 2.5  standing across the room     0.0122      0.0109     15.3  open
 4.2  kitchen doorway              0.0061      0.0065      9.3  open

So the answer volume 6 wrote down as unanswerable is yes, barely, in a quiet house. From the kitchen doorway a normal speaking voice lands at 0.0061 against a gate of 0.005: it opens, with 22 percent of margin. That is not comfort, it is a measurement sitting one small change away from failing, and the honest reading is that her hearing ends at about that doorway.

The free-field column is the reason to trust the rest. It predicts each level from the first one using nothing but distance, and the two middle rows come in above the prediction because a room is not open air: the walls return energy the free-field model assumes is gone forever. The doorway row falls slightly below prediction instead, because at 4.2 metres you are also off to the side of an array that points at the desk. When measurements and a simple model disagree in a direction you can explain, both are probably telling the truth.