Voice Note Processing

When a voice note arrives (Slack voice message), the gateway saves the audio to /opt/data/cache/audio/audio_*.m4a and appends a note like:

[voice message could not be transcribed automatically; the audio is available at: /opt/data/cache/audio/audio_22932ad58a12.m4a]

The audio file path IS in the user's message. Process it immediately.

Workflow

1. Transcribe with Whisper

/opt/data/home/.local/share/uv/tools/openai-whisper/bin/whisper \
  /opt/data/cache/audio/audio_<id>.m4a \
  --model small \
  --output_dir /tmp \
  --output_format txt

Model: small (~244M params). Good balance for voice notes. tiny is faster but less accurate for accented speech; medium is better but slower on CPU (only use if small produces garbled output).
FP16 warning on CPU is normal — ignore it.
Language auto-detection works well; add --language en to skip detection for known-English notes.
5-min voice note ≈ 15-20s on CPU; 10-min ≈ 30-40s.

2. Read the Transcript

The transcript file is at /tmp/audio_<id>.txt. Read it — this IS the user's message.

3. Act on the Content

The transcript is the user speaking directly. Process it like any other user message:

If it's a task/request → do it
If it's a log/journal entry → save to appropriate wiki location
If it's coding instructions → execute
If it's a question → answer

4. Save Transcript (Optional)

For voice notes worth keeping (logs, ideas, decisions), save the transcript to the wiki:

/opt/data/wiki/consume/raw/voice-notes/<YYYY-MM-DD>-<brief-slug>.txt

5. Delete the Audio File

rm /opt/data/cache/audio/audio_<id>.m4a

Always delete the audio after processing — no raw audio files lying around.

Also clean up the transcript file from /tmp unless it was saved to wiki.

Model Sizing Guide

Model	Params	Speed (10min audio)	Accuracy	When to use
tiny	39M	~8s	Lower	Quick tests only
small	244M	~30s	Good	Default — daily voice notes
medium	769M	~90s	Better	Important transcription, accented speech
large	1550M	~3min	Best	Publishable transcripts (podcast, talk)

Start with small. If the transcript has obvious errors, re-run with --model medium.

Pitfalls

Whisper path: Must use full path — it's installed via uv tool install openai-whisper, not in PATH.
CPU only: No GPU on this machine. FP16 not supported — the warning is harmless.
m4a format: Whisper handles .m4a natively (ffmpeg is bundled).
Concurrent: Don't run two whisper processes at once — CPU-bound, they'll fight.
Large files: 30+ min audio takes minutes. If it's clearly a podcast-length recording, use --model medium for quality and be patient.
Slack gateway note: The "[voice message could not be transcribed automatically]" line is auto-generated by Slack/gateway — it doesn't mean whisper failed, it's just Slack's built-in transcription didn't run. Ignore it and run whisper yourself.

voice-note