Local TTS Queue
Requirements
- - Required credential: INLINECODE0
- Recommended env vars:
ELEVENLABS_VOICE_ID, INLINECODE2 - Runtime tools:
python3, curl, and one local playback backend (mpv, ffplay, afplay, paplay, or PowerShell sound player) - Network destination for synthesis/preflight: INLINECODE9
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
- 1. 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.sh and compare against SLOs in references/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: INLINECODE15
- Worker (foreground): INLINECODE16
- Worker daemon: INLINECODE17
- Status: INLINECODE18
- Benchmark harness: INLINECODE19
- Fast foreground benchmark:
scripts/benchmark-autonoannounce.sh 5
- Full diagnostic benchmark:
scripts/benchmark-autonoannounce.sh 5 --status both --output full
- - First-run interactive setup:
skills/autonoannounce/scripts/setup-first-run.sh (shell wrapper) - Cross-platform first-run CLI: INLINECODE23
- Backend detection (OS-aware): INLINECODE24
- ElevenLabs capability preflight:
skills/autonoannounce/scripts/elevenlabs-preflight.sh (includes short 429 retry/backoff for SFX probe) - Earcon library manager (durable categories/cache): INLINECODE26
- Cross-platform playback runner: INLINECODE27
- Playback backend/device probe: INLINECODE28
- Playback backend startup validator: INLINECODE29
- Playback confirmation tone: INLINECODE30
- v0.2 smoke tests: INLINECODE31
- Race/concurrency stress checks: INLINECODE32
References map
- - Runbook: INLINECODE33
- Config contract: INLINECODE34
- Performance SLOs and interpretation: INLINECODE35
- Foreground-latency optimization: INLINECODE36
- Durable earcon categories and cache: INLINECODE37
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.
本地TTS队列
前提条件
- - 必需凭证：ELEVENLABSAPIKEY
- 推荐环境变量：ELEVENLABSVOICEID、ELEVENLABSMODELID
- 运行时工具：python3、curl，以及一个本地播放后端（mpv、ffplay、afplay、paplay或PowerShell音频播放器）
- 合成/预检网络目标：https://api.elevenlabs.io
概述
使用此技能可保持本地语音的快速、可靠和策略合规性，通过将入队视为发射后不管并将合成/播放隔离在队列工作器内部实现。
快速入门工作流程
- 1. 使用scripts/tts-queue-status.sh确认队列健康状态。
- 使用scripts/speak-local-queued.sh 文本将语音加入队列。
- 如果音频未播放，请检查工作器日志和references/runbook.md中的操作手册步骤。
- 如需延迟调优，运行scripts/benchmark-autonoannounce.sh并与references/perf-slos.md中的服务等级目标进行对比。
操作规则
- - 保持生产者路径非阻塞：入队后立即返回。
- 将合成/播放限制在工作器独占的执行路径中。
- 优先对队列进行较少的大批量写入（尽可能合并突发流量）。
- 使用策略安全的输出通道：受保护用户使用本地扬声器；不使用Discord语音文件回退。
- 将单个失败项视为独立事件：有限重试后转入死信队列；不阻塞整个队列。
命令
- - 入队：scripts/speak-local-queued.sh <文本>
- 工作器（前台）：scripts/tts-queue-worker.sh
- 工作器守护进程：scripts/tts-queue-daemon.sh
- 状态：scripts/tts-queue-status.sh
- 基准测试工具：scripts/benchmark-autonoannounce.sh
- 快速前台基准测试：scripts/benchmark-autonoannounce.sh 5
- 完整诊断基准测试：scripts/benchmark-autonoannounce.sh 5 --status both --output full
- - 首次运行交互式设置：skills/autonoannounce/scripts/setup-first-run.sh（Shell封装）
- 跨平台首次运行CLI：skills/autonoannounce/scripts/setupfirstrun.py
- 后端检测（操作系统感知）：skills/autonoannounce/scripts/backend-detect.sh
- ElevenLabs能力预检：skills/autonoannounce/scripts/elevenlabs-preflight.sh（包含针对SFX探测的短时429重试/退避）
- 提示音库管理器（持久化分类/缓存）：skills/autonoannounce/scripts/earcon-library.sh
- 跨平台播放运行器：skills/autonoannounce/scripts/play-local-audio.sh
- 播放后端/设备探测：skills/autonoannounce/scripts/playback-probe.sh
- 播放后端启动验证器：skills/autonoannounce/scripts/playback-validate.sh
- 播放确认音：skills/autonoannounce/scripts/playback-test.sh
- v0.2冒烟测试：skills/autonoannounce/scripts/test-v0.2.sh
- 竞态/并发压力检查：skills/autonoannounce/scripts/race-stress.sh
参考映射
- - 操作手册：references/runbook.md
- 配置契约：references/config-contract.md
- 性能SLO及解读：references/perf-slos.md
- 前台延迟优化：references/front-path-optimization.md
- 持久化提示音分类和缓存：references/earcon-library.md
执行检查清单
- - 验证前提条件（ELEVENLABSAPIKEY、ELEVENLABSVOICEID、mpv）。
- 在调优性能前验证队列路径和锁行为。
- 在进行队列/工作器更改前测量基线。
- 每次实质性更改后重新运行基准测试。
- 在任务摘要中记录最终的p50/p95延迟和队列等待差值。
