Skip to content

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-main plays a WAV through sounddevice, 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 and play() 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.

play(name)

Fire a cue. Returns True if something was actually played.

Called from the key-tap callback thread, so it must not block: NSSound plays asynchronously, and the afplay fallback is spawned, never waited on.

prime()

Synthesise, cache and preload. True when at least one cue is ready.

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.