audio_cues
diapason.desktop.audio_cues
¶
Audible feedback for dictation — a blip down, a blip up.
Push-to-talk is a blind contract: you hold a key and hope a microphone opened. Everything that can go wrong (permission missing, tap starved, key not registered) fails the same silent way, so the single most useful signal is a short sound the instant the key is seen. It confirms the tap fired, before any device work has happened.
Two design choices worth stating:
- The tones are synthesised, not shipped.
jarvis-mainplays a WAV throughsounddevice, but its only asset is a 14.5-second spoken welcome phrase — a start cue must be under a tenth of a second. Rather than commit a binary asset that has to be found, licensed and reviewed, the cues are ~40 lines of arithmetic, so they are diffable, tunable, and testable without a sound card. - Playback goes through NSSound, not
sounddevice. The capture stream is a PortAudio input stream opening at the same moment; driving output through the same library invites device contention on the one code path that must never stall. NSSound loads the clip into memory once at startup andplay()returns immediately, so the cue costs nothing at keypress.
Nothing here is allowed to break dictation: every failure degrades to silence. A missing sound is a cosmetic loss; a raised exception on the tap callback thread is a dead hotkey.
CuePlayer
¶
Plays the cues, or silently does nothing. Never raises.
prime() does all the expensive work — synthesis, disk write, NSSound
load — so that play() is a single message send on the hot path.
cue_wav(name)
¶
WAV bytes for a named cue. Raises KeyError on an unknown name.
glide(f0, f1, duration_s, *, sample_rate=SAMPLE_RATE, amplitude=AMPLITUDE)
¶
A sine sweeping f0 → f1, enveloped so it neither clicks nor thumps.
The phase is integrated rather than computed per-sample from the
instantaneous frequency (sin(2π f(t) t)), which would fold the
frequency change into the argument twice and bend the pitch the wrong
way. Accumulating 2π f(t)/rate keeps the waveform continuous.
wav_bytes(samples, *, sample_rate=SAMPLE_RATE)
¶
16-bit mono PCM WAV, stdlib only.