Skip to content

Lesson 2 · Record a visit

Thirty minutes. At the end you have a WAV file of your own voice and understand why it is 16 kHz mono.

The whole script

steps/01_record.py is the entire lesson. It is 35 lines; read it first.

steps/01_record.py
"""Lesson 2 - record a visit to a WAV file. No scribe package needed.

    python steps/01_record.py visit.wav

Speak, then press Enter to stop. Produces 16 kHz mono 16-bit PCM, which is
what every speech model wants.
"""
import queue
import sys
import threading

import sounddevice as sd
import soundfile as sf

RATE = 16000                      # samples per second. Speech models were trained on this rate.
out = sys.argv[1] if len(sys.argv) > 1 else "visit.wav"

q: "queue.Queue" = queue.Queue()  # the audio callback runs on a separate thread; hand blocks over safely
stop = threading.Event()


def on_audio(indata, frames, time_info, status):
    if status:
        print(status, file=sys.stderr)
    q.put(indata.copy())


threading.Thread(target=lambda: (input(), stop.set()), daemon=True).start()
print("Recording. Press Enter to stop.")

with sf.SoundFile(out, mode="w", samplerate=RATE, channels=1, subtype="PCM_16") as f:
    with sd.InputStream(samplerate=RATE, channels=1, dtype="int16", callback=on_audio):
        while not stop.is_set():
            try:
                f.write(q.get(timeout=0.2))
            except queue.Empty:
                pass

print(f"Saved {out}")

Run it:

python steps/01_record.py myvisit.wav

Talk for twenty seconds. Role-play both sides if you like. Press Enter.

What the lines mean

RATE = 16000. Speech models are trained on 16,000 samples per second. CD audio is 44,100. Higher does not help the model and triples the file size. One channel (mono) for the same reason: the model does not use stereo.

The queue. The sound card delivers audio in small blocks on its own thread, dozens of times a second. If you write to disk inside that callback and the disk hiccups, you drop audio. So the callback only drops the block in a queue, and the main loop writes. This pattern, "capture thread hands off to worker", shows up again in every real-time system.

PCM_16. Sixteen-bit integers, the plain uncompressed WAV format. A 15-minute visit is about 29 MB. Fine on disk, and it means the transcriber never has to decode anything.

Microphones matter more than code

The single biggest quality lever in this whole pipeline is the microphone and where it sits. In order of impact:

  1. Distance. A USB conference mic on the desk between you and the patient beats a laptop mic by a wide margin. Under a metre to each speaker is the goal.
  2. Room. Hard floors and bare walls echo. A rug and a curtain are real improvements.
  3. Gain. Too quiet is recoverable; clipped is not. The browser recorder in Lesson 6 turns on automatic gain control; this script does not.

List what the system sees:

scribe mics

Pick one by index or name:

SCRIBE_MIC=1 scribe record myvisit.wav

The package version

scribe record in scribe/audio.py is the same loop with a device option, a time limit option, and a load() helper that turns any audio file (WAV, MP3, the browser's WebM) into the float array the transcriber wants. It uses faster-whisper's bundled decoder, so you do not need ffmpeg installed.

scribe record myvisit.wav --seconds 30

Try

  • Record the same sentence from across the room and up close. Transcribe both in the next lesson. The difference is your argument for buying a mic.
  • Open the WAV in Audacity or any editor and look at the waveform. Flat tops are clipping.

Safety

You have just created PHI if anyone real was recorded. Even in practice, treat test recordings as if they were: keep them in the project folder, which scribe purge cleans, not in Downloads.

Next: Lesson 3 · Transcribe.