tts (Punt Labs)

punt vox

为您的AI编码助手提供语音。

    

当Claude Code完成任务、出现错误或需要您的批准时，您会听到它。无需查看终端。继续工作；你的助手会告诉你发生了什么事。

平台： macOS、Linux

听到它

vox使用ElevenLabs v3生成的真实样本。前三个是相同的回顾，但不同 /vibe 语气——富有表现力的标签在不改变单词的情况下改变声音的发音。

|示例|振动|声音|| |--------|------|-------|-| |任务回顾|中立|萨拉| 听 | |同样的回顾| [excited] |萨拉| 听 | |同样的回顾| [weary] [sighs] |萨拉| 听 | |任务完成|中立|玛蒂尔达| 听 |

快速开始

curl -fsSL https://raw.githubusercontent.com/punt-labs/vox/4ced624/install.sh | sh

重新启动克劳德代码，然后：

/vox y        # hear when tasks complete or need input
/recap        # spoken summary of what just happened

Manual install (if you already have uv)

uv tool install punt-vox
vox install
vox doctor

Verify before running

curl -fsSL https://raw.githubusercontent.com/punt-labs/vox/4ced624/install.sh -o install.sh
shasum -a 256 install.sh
cat install.sh
sh install.sh

配置提供者

快速入门让您使用操作系统的内置语音运行-- say 在macOS上， espeak-ng 在Linux上。要获得自然的声音，请配置任何云提供商。对于 /vibe 表达性标签([excited], [weary], [sighs]等等）你特别需要ElevenLabs——这是目前唯一支持它们的提供商。

1.获取API密钥

2.将密钥添加到 ~/.punt-labs/vox/keys.env

密钥文件位于您的主目录中，归您所有——在您的普通编辑器中打开它，无需sudo：

nano ~/.punt-labs/vox/keys.env   # or vi, code, etc

粘贴任何适用的线条。所有这些都是可选的；vox自动检测配置了哪些提供程序。

# ElevenLabs — recommended
ELEVENLABS_API_KEY=sk_...

# OpenAI
OPENAI_API_KEY=sk-proj-...

# AWS Polly via an aws CLI profile (recommended if you use the AWS CLI)
AWS_PROFILE=default
AWS_DEFAULT_REGION=us-east-1

# AWS Polly via raw credentials (alternative to a profile)
# AWS_ACCESS_KEY_ID=AKIA...
# AWS_SECRET_ACCESS_KEY=...
# AWS_DEFAULT_REGION=us-east-1

# Optional: pin a specific provider.
# Auto-detect order: ElevenLabs > OpenAI > Polly > say (macOS) / espeak (Linux).
TTS_PROVIDER=elevenlabs

3.重新启动守护进程以获取更改

# Linux
sudo systemctl restart voxd

# macOS
sudo launchctl kickstart -k system/com.punt-labs.voxd

这是常规密钥管理的唯一sudo提示符-- systemctl 和 launchctl 是系统级守护进程管理器，始终需要root来管理服务。编辑 keys.env 它本身是免费的sudo。

4.验证

vox doctor                         # report system checks and the daemon's active provider
vox unmute "hello from vox"        # speak through the default provider

vox doctor 报告Python版本、ffmpeg/espeak存在、守护进程状态以及正在运行的守护进程当前使用的提供程序。 vox unmute 应该在几秒钟内通过你的演讲者说出这个短语。

如果有什么不起作用，守护进程会登录 ~/.punt-labs/vox/logs/voxd.log 捕获spawn命令、音频会话环境、退出代码、运行时间和播放器stderr——足够详细，无需任何额外工具即可诊断大多数故障。

升级

uv tool upgrade punt-vox 替换了磁盘上的轮子，但确实如此 不 重新启动长时间运行的 voxd 守护进程。在循环守护进程之前，任何涉及守护进程行为的更改——新的WebSocket字段、新的去重语义、voxd必须解析的新CLI标志——都将被旧进程默默地忽略。升级后始终重新启动守护进程：

# macOS or Linux — identical command now
uv tool upgrade punt-vox
vox daemon restart

跑 vox daemon restart 作为您的普通用户， 不 在...之下 sudo。该命令拒绝以root身份运行，并且仅在两次服务管理器调用时在内部提示使用sudo(systemctl/launchctl)它通过服务管理器停止voxd，等待端口释放，再次启动，并轮询经过身份验证的健康端点，直到确认新进程正在运行。它会在成功时打印新的PID和端口，或指向您 ~/.punt-labs/vox/logs/voxd.log 失败。

要确认守护进程和已安装的控制盘一致：

vox doctor

vox doctor 现在报告正在运行的守护进程版本以及可达性检查。当正在运行的守护程序与磁盘上安装的轮子不匹配时，doctor会发出黄色 ⚠ Daemon: running ... (version X — wheel has Y, run 'vox daemon restart' to refresh) 警告。退出代码保持为0——守护进程仍在运行——但警告在冒烟测试时而不是在生产中捕获过时的守护进程。

医生也检查 ~/.config/systemd/user/vox.service 在Linux上，如果它存在的话。早期的安装布局留下了一个用户级单元 ExecStart=.../vox serve，CLI中不再存在的子命令；任何幸存的文件崩溃都会在systemd重启计划中循环。当引用的子命令不在当前CLI中时，Doctor会大声失败并给出补救提示，以及 vox daemon install 现在，升级时会自动删除过时的单元。macOS没有用户级systemd，因此检查被关闭。

特性

• 通知层 ---任务完成时进行口头总结，克劳德需要输入时发出提示音
• 会议氛围 --- /vibe 为所有演讲设定基调。自动模式读取会话信号（测试结果、lint、git ops）并调整语音。手动模式允许您自己设置。ElevenLabs表达性标签([weary], [excited], [sighs])为每一句话上色。
• 五家供应商 ---ElevenLabs、OpenAI、AWS Polly、macOS say，以及Linux espeak-ng完整的体验（自然的声音、富有表现力的标签、， /vibe)需要ElevenLabs。
• 仅选择加入 ---在启用之前没有音频，没有惊喜
• 语音或蜂鸣声 --- /mute 切换到音频音调，无TTS API呼叫
• 优雅的缺席 ---如果未安装punt-vox，Claude Code的工作方式与以前完全相同
• MCP本地 ---作为带有斜线命令和钩子的Claude Code插件运行
• 音频守护程序 --- voxd 是一个处理合成和回放的系统级音频服务器。跨会话消除音频重复，序列化播放，缓存合成结果
• 背景音乐 --- /music on 通过ElevenLabs Music API生成振动驱动的乐器曲目，并在工作时以低音量循环播放。当振动发生变化时，会生成一首新曲目以进行匹配。样式修改器(/music on style techno)跨调用持久化。需要ElevenLabs付费计划；每条赛道花费约2000学分

远程音频

在无头服务器或云VM上运行Claude Code，并在本地计算机上收听音频。集 VOXD_HOST, VOXD_PORT，以及 VOXD_TOKEN 在远程主机上指向本地voxd，或使用SSH隧道进行网络边界穿越。

看 docs/remote-setup.md 了解完整的演练（直接网络和SSH隧道方法）。

它看起来像什么

启用通知

> /vox y

Vox enabled. You'll hear when tasks finish or need approval.
Pick a voice with /unmute @.

获取回顾

> /recap

Speaking: "I refactored the authentication module into three files, added
comprehensive tests for the token refresh flow, and fixed a race condition
in the session middleware. All 47 tests pass."

营造氛围

> /vibe banging my head against the wall

Vibe: banging my head against the wall → [frustrated] [sighs] [manual]

自动模式（默认）读取会话信号并自动适应——在一系列测试失败后，语音会响起 [weary]，成功发布后，听起来 [excited].

仅切换到蜂鸣器

> /mute

Muted — chimes only.

编钟是情绪感知的：当一种氛围活跃时，编钟的音调会发生变化以匹配（明亮表示快乐，黑暗表示沮丧）。八个不同的信号（测试通过/失败、lint通过/失败，git推送、合并冲突、完成、提示）×三个情绪变体=24个提示资产。

命令

提供商

完整的体验——自然的声音，带有富有表现力的标签，能够回应 /vibe ---需要ElevenLabs。其他提供商是ElevenLabs不可用环境的后备方案。

自动检测顺序：ElevenLabs>OpenAI>Polly（如果AWS凭据有效）>say（macOS）/espeak（Linux）。

用于计费隔离的Per-call API密钥

如果您维护多个供应商API密钥用于成本归属（ 例如，为不同的项目分别设置ElevenLabs密钥），您可以 为任何呼叫传递每次呼叫覆盖 vox unmute 调用。超控 仅限每次通话：从不坚持 keys.env，从未被记录 守护进程，永远不会回显到stdout，永远不会对并发请求可见 在同一个守护进程上。支持四条输入路径，从大多数到 最不安全：

1. 环境变量 （建议用于脚本编写）：

   export VOX_API_KEY=$(pass show vox/proj_a)
   vox unmute "billable to project A"

在Linux上， VOX_API_KEY 通过以下方式暴露 /proc/ /environ, 其通常仅可由进程所有者读取。macOS有 没有Linux风格 /proc 文件系统，因此不会暴露env变量 默认情况下是这样，但它们通常仍然不那么明显 比 argv （其中 ps 在任何共享系统上打印）。不管怎样， env变量比直接传递密钥安全得多 命令行。

1. 文件 （建议用于存储密钥）：

   vox unmute "billable to project A" \
     --api-key-file ~/.config/vox/key_project_a.txt

文件应为模式0600（仅限所有者读/写）。 vox 警告 如果设置了任何组或其他权限位并给出建议 chmod 600.

1. 标准输入 （建议用于密码管理器）：

   pass show vox/proj_a | vox unmute "billable to project A" --api-key-stdin

从stdin读取一行。拒绝阅读tty的文章 遗忘的管道会大声故障，而不是堵塞交互式管道 提示。

1. 命令行 （仅演示-- 不 真实凭证）：

   vox unmute "billable to project A" --api-key sk_demo_key

警告: --api-key 在命令行上显示值 通过 ps （在Linux上， /proc/*/cmdline)、外壳历史，以及 终端录音。 vox 每当您执行以下操作时，都会打印stderr警告 使用它。使用其他三条路径中的一条作为真实凭据。

这四条路径是相互排斥的；指定多个是 错误。这是 不 多租户隔离——vox是一个单用户 工具。该功能用于将合成成本归因于权利 在一个用户的帐户内进行项目，而不是隔离租户。

每次呼叫 api_key 调用绕过合成缓存，因此每个 调用到达提供者；使用匿名电话(keys.env)for 缓存命中。

建筑

Claude Code ◄── stdio ──► vox mcp ── WebSocket ──► voxd :8421
                                                      │
Hook scripts ──► vox hook  ── WebSocket ──►    │
                                                      │
Shell        ──► vox unmute "hi"  ── WebSocket ──►    │
                                                      ▼
                                                   speakers

voxd 是一个系统级音频守护进程。它通过TTS提供商合成文本，并通过扬声器播放音频。它拥有播放队列（顺序，无重叠），在5秒内消除相同请求的重复，并缓存合成结果。它对MCP、钩子、项目或Claude Code一无所知。

vox mcp 是一个轻量级的stdio MCP服务器，每个Claude Code会话一个。它在内存中保存会话状态（语音、氛围、通知模式），并将合成委托给 voxd 通过WebSocket。它从Claude Code继承其工作目录，并找到 .punt-labs/vox/ 从那里走上去。

vox hook 处理程序调用 voxd 用于钟声和演讲。Hook shell脚本是根据 挂钩标准.

vox unmute 其他CLI命令是一次性WebSocket客户端 voxd.

状态路径

voxd 以单个用户身份运行(User= 在systemd单元中， UserName 在launchd-plist中），因此其所有状态都是针对每个用户的，而不是系统共享的。所有内容都位于安装用户的主目录下——否 /etc，没有 /var，在macOS和Linux上的布局相同。

服务安装

vox daemon install    # registers service, writes keys.env, starts voxd

vox在安装系统服务单元时会提示您输入一次sudo密码。其他一切都像你的普通用户一样运行。这 keys.env 文件和所有其他每个用户的状态都是在您的主目录中以正常的用户权限创建的——没有chown、没有fd技巧、没有符号链接防御。守护进程以安装用户身份运行，而不是以root身份运行——它需要与桌面会话绑定的音频设备访问权限。

从v3或v4.0.x升级？ 如果您在v3.0.0（2026-03-29）之前配置了云提供商密钥，则升级后它们将自动重新工作。v3将voxd的配置目录移动到 /etc/vox/ 但从未迁移您现有的 ~/.punt-labs/vox/keys.env --此版本将恢复路径，您的v3之前的密钥将重新联机，无需任何手动干预。

会话状态

会话状态（语音、提供者、氛围、通知模式）存在于MCP服务器的内存中。守护进程在会话方面是无状态的。每个项目配置都存在 .punt-labs/vox/ 作为两个文件： vox.md （追踪、持久的偏好）和 vox.local.md （gitignored，类似短暂会话状态的vibe信号）。MCP服务器在启动时读取这些数据；钩子处理程序读写 vox.local.md 用于信号积累。守护进程从不读取任何文件。

守护进程重新启动

MCP会话（克劳德代码↔ vox mcp)stdio不受守护进程重启的影响。WebSocket连接(vox mcp ↔ voxd)自动重新连接。会话数据不会丢失。

命令行界面

punt-vox也是一个独立于Claude Code的TTS工具。

vox unmute "Hello world"                       # Synthesize + play
vox unmute "Wall broadcast" --once 600         # Dedup identical text within 600s (for N-session broadcasts)
vox record "Hello world" -o hello.mp3          # Synthesize + save
vox record --from segments.json                # From JSON segments file
vox vibe excited                               # Set session mood
vox notify y                                   # Enable notifications
vox notify c                                   # Continuous spoken mode
vox speak n                                    # Chimes only
vox voice matilda                              # Set session voice
vox music on                                   # Start background music
vox music on --style techno                    # Start music with style modifier
vox music off                                  # Stop background music
vox status                                     # Current state
vox version                                    # Print version
vox doctor                                     # Check setup
vox install                                    # Install Claude Code plugin
vox mcp                                        # Start MCP server (stdio)
voxd                                           # Start audio daemon
vox daemon install                             # Register voxd as system service + write API keys (prompts once for sudo)
vox daemon status                              # Check if daemon is running

环境变量

提供程序API密钥(ELEVENLABS_API_KEY, OPENAI_API_KEY, AWS_*)生活在 ~/.punt-labs/vox/keys.env，而不是在你的shell rc中。看 配置提供者 完整的演练。

vox daemon install 还有种子 keys.env 对于运行安装的shell中设置的任何提供者密钥，请在 .envrc 或者在运行安装程序之前进行类似操作。无论哪种方式，安装后的编辑都会直接进入文件。

路线图

已发货

• 麦克风API：统一 unmute/record/vibe/who 基于分段输入的MCP工具
• 通知层： /vox y|n|c, /mute, /unmute, /recap，停止+通知挂钩
• 多提供商TTS引擎：ElevenLabs、AWS Polly、OpenAI、macOS say，Linux espeak-ng
• Claude Code插件：市场安装、MCP服务器、斜线命令
• CLI：取消静音、录制、氛围、开/关、静音、版本、状态、医生
• 双通道显示： ♪ 带有语音/提供商上下文的面板摘要
• ElevenLabs流媒体API，用于较低时间的第一音频
• /vibe 具有自动、手动和关闭模式——ElevenLabs富有表现力的标签为每句话着色
• 自动振动信号累加器：测试通过/失败、lint、git ops馈送情绪检测
• 每个信号的钟声资产和氛围驱动的钟声，具有情绪感知的音调变化
• 音频守护程序(voxd)：系统级音频服务器，具有内存中播放队列、去重、合成缓存、launchd/systemd服务管理

即将推出

文档

建筑（PDF） | 设计日志 | 测试 | 更新日志

发展

uv sync --all-extras    # Install dependencies
make check              # Run all quality gates

许可证

麻省理工学院