Local TTS Queue
Requirements
- Required credential:
ELEVENLABS_API_KEY - Recommended env vars:
ELEVENLABS_VOICE_ID,ELEVENLABS_MODEL_ID - Runtime tools:
python3,curl, and one local playback backend (mpv,ffplay,afplay,paplay, or PowerShell sound player) - Network destination for synthesis/preflight:
https://api.elevenlabs.io
Overview
Use this skill to keep local speech fast, reliable, and policy-compliant by treating enqueue as fire-and-forget and isolating synthesis/playback inside the queue worker.
Quick start workflow
- Confirm queue health with
scripts/tts-queue-status.sh. - Enqueue speech with
scripts/speak-local-queued.sh "text". - If audio does not play, inspect worker logs and runbook steps in
references/runbook.md. - For latency tuning, run
scripts/benchmark-autonoannounce.shand compare against SLOs inreferences/perf-slos.md.
Operating rules
- Keep the producer path non-blocking: enqueue then return immediately.
- Keep synthesis/playback in worker-only execution paths.
- Prefer fewer larger writes to the queue (coalesce bursty traffic when possible).
- Use policy-safe output lanes: local speaker for protected users; no Discord voice-file fallback.
- Treat one failed item as isolated: retry with bounds, then dead-letter; do not stall entire queue.
Commands
- Enqueue:
scripts/speak-local-queued.sh "<text>" - Worker (foreground):
scripts/tts-queue-worker.sh - Worker daemon:
scripts/tts-queue-daemon.sh - Status:
scripts/tts-queue-status.sh - Benchmark harness:
scripts/benchmark-autonoannounce.sh- Fast foreground benchmark:
scripts/benchmark-autonoannounce.sh 5 - Full diagnostic benchmark:
scripts/benchmark-autonoannounce.sh 5 --status both --output full
- Fast foreground benchmark:
- First-run interactive setup:
skills/autonoannounce/scripts/setup-first-run.sh(shell wrapper) - Cross-platform first-run CLI:
skills/autonoannounce/scripts/setup_first_run.py - Backend detection (OS-aware):
skills/autonoannounce/scripts/backend-detect.sh - ElevenLabs capability preflight:
skills/autonoannounce/scripts/elevenlabs-preflight.sh(includes short 429 retry/backoff for SFX probe) - Earcon library manager (durable categories/cache):
skills/autonoannounce/scripts/earcon-library.sh - Cross-platform playback runner:
skills/autonoannounce/scripts/play-local-audio.sh - Playback backend/device probe:
skills/autonoannounce/scripts/playback-probe.sh - Playback backend startup validator:
skills/autonoannounce/scripts/playback-validate.sh - Playback confirmation tone:
skills/autonoannounce/scripts/playback-test.sh - v0.2 smoke tests:
skills/autonoannounce/scripts/test-v0.2.sh - Race/concurrency stress checks:
skills/autonoannounce/scripts/race-stress.sh
References map
- Runbook:
references/runbook.md - Config contract:
references/config-contract.md - Performance SLOs and interpretation:
references/perf-slos.md - Foreground-latency optimization:
references/front-path-optimization.md - Durable earcon categories and cache:
references/earcon-library.md
Execution checklist
- Verify prerequisites (
ELEVENLABS_API_KEY,ELEVENLABS_VOICE_ID,mpv). - Validate queue paths and lock behavior before tuning performance.
- Measure baseline before making queue/worker changes.
- Re-run benchmark after each material change.
- Record final p50/p95 latency and queue-wait deltas in the task summary.