oma-voice

Voice Skill - 语音与本地音频处理

调度

目标

通过本地 Voicebox 应用生成和转录语音，并使用本地媒体工具处理现有音频。Voicebox 负责合成引擎和语音档案；FFmpeg 负责文件转换、时长调整和响度处理。

意图特征

• 用户要求生成语音、朗读文本、制作配音，或根据文本创建 mp3 或 wav 文件。
• 用户希望将音频文件转录为文本、会议记录或文字稿。
• 用户要求在长任务完成或工作流步骤受阻时收到语音通知。
• 其他技能需要本地音频生成基础设施。
• 用户需要调整现有语音以适应指定时长，或对其进行重采样、转换或响度归一化。

适用场景

• 为 Agent 任务完成或受阻情况生成简短的通知音频。
• 为应用和内容制作配音、旁白或音频素材（mp3 或 wav）。
• 将本地音频文件（mp3、wav、m4a、webm、flac）转录为 Markdown。
• 对同一文本使用不同的 profile id 重新生成语音，以比较语音档案。
• 处理现有音频素材，包括用于 oma-video 配音任务的语音。

不适用场景

• 云端 TTS 或高保真多语言云端语音 -> 超出范围；未来可扩展为支持多供应商。
• 在终端中实时循环进行麦克风听写 -> 使用 Voicebox 应用内置的热键听写功能。
• 上传语音克隆样本并创建语音档案 -> 在 Voicebox 桌面应用 UI 中完成。
• 视频编辑和音视频编排 -> 使用 oma-video；音乐和音效设计不在范围内。
• Stories Editor 多语音时间线编排 -> 使用 Voicebox 应用 UI。

预期输入

• TTS：文本（每次调用不超过 5000 个字符）、可选的 profile id、engine、language 和 output path。
• STT：音频文件路径（绝对路径或相对于 $CWD 的路径）、可选的语言提示。
• 通知：简短消息（不超过 240 个字符），从配置中解析 profile id。
• 处理：现有音频路径、所需操作，以及任何指定的时长、采样率、声道布局、响度或格式限制。根据需求说明确定目标，不使用通用的母带处理预设。

预期输出

• TTS：位于 .agents/results/voice/{timestamp}-{shortid}/output.{wav|mp3} 的音频文件（wav 是 Voicebox 的原生 TTS 输出格式；可选用本地 ffmpeg 转码为 mp3），以及 manifest.json。
• STT：位于 .agents/results/voice/transcripts/{timestamp}-{shortid}/ 的 transcript.md，以及 manifest.json。
• 通知：通过 Voicebox 临时播放；默认不写入磁盘。
• 处理：单独的处理后音频文件，以及包含源文件/输出文件路径、操作和测得音频属性的 manifest.json。保留源文件不变。只有 Voicebox 实际生成音频时，才会包含生成 id。

依赖项

• 仅处理：已安装 ffmpeg 和 ffprobe；无需 Voicebox 应用或语音档案。
• 生成/转录：已安装并在本地运行的 Voicebox 桌面应用。
• 仅生成/转录：已注册 Voicebox MCP（claude mcp add --transport http voicebox http://127.0.0.1:17493/mcp）。
• 仅 TTS：至少在 Voicebox 应用 UI 中创建了一个语音档案。
• 仅 TTS：可为所选语音档案预先下载引擎模型。

控制流特性

• 根据模式（notify、asset、transcribe）、语言和语音档案可用性进行分支处理。
• 通过 MCP 工具调用 Voicebox，并使用 REST GET /health 进行握手探测。
• 读取输入音频文件，并写入生成的音频和清单文件。
• 在首次成功调用 tools/list 后缓存发现的 MCP 工具名称。

结构流程

Entry

1. 检测请求的模式：通知、资源 TTS、转录或现有音频处理。对于处理，直接遵循 resources/audio-processing.md，然后再进行任何 Voicebox 健康状态、配置文件或模型查询。
2. 通过 MCP 握手或 GET /health 确认 Voicebox 可访问。
3. 仅在首次运行时调用 MCP tools/list，并缓存解析后的工具名称。
4. 对于通知或资源 TTS，解析目标语音配置文件 ID。对于转录，验证音频输入并继续，无需配置文件。

Scenes

1. PREPARE：解析操作及其输入。Voicebox 模式使用文本/音频和语言；TTS 还需要配置文件。文件处理使用源文件和请求的媒体属性。
2. ACQUIRE：如果缺少必需信号，执行一次澄清流程。
3. ACT：调用相应的 MCP 工具（TTS 或 STT），或使用本地 FFmpeg 命令处理现有资源。
4. VERIFY：确认响应包含音频输出或转录内容。验证清单字段。
5. FINALIZE：在输出文件旁写入 manifest.json。向用户报告路径或转录内容。

Transitions

• 对于生成/转录，如果 Voicebox 无法访问，则显示安装或启动提示并退出。不要尝试自动重新启动。现有文件处理不受影响。
• 回环地址指向进程自身的主机或容器。应从主机调用主机上的 Voicebox 服务，然后将生成的文件传输到任务容器；容器的 127.0.0.1 不会探测到主机应用。
• 对于定时旁白，保留原始生成结果。选择支持相应语言且可用的配置文件，测量原始时长，并使用 resources/audio-processing.md 进行适配。神经引擎或正确的响度并不能证明发音和韵律自然。
• 如果 TTS 请求没有可用的配置文件，提示用户前往 Voicebox 应用 UI 创建配置文件，然后退出。转录请求不需要配置文件。
• 如果 TTS 请求超过 5000 个字符，询问用户是截断还是拆分。v1 中不要自动分块。
• 如果 STT 输入超过 30 分钟，询问用户是否继续。不要自动拆分。
• 如果所选引擎模型尚未加载，在触发下载前询问用户。

Failure and recovery

Failure	Recovery
Voicebox 应用未运行	打印安装/启动提示，退出代码为 5
没有用于 TTS 的语音配置文件	打印“在 Voicebox 中创建配置文件”的提示，退出代码为 3
缺少引擎模型	在触发下载前询问用户
输出路径位于 $PWD 之外	使用明确请求的路径；仅当目标路径不明确或会覆盖无关数据时询问
TTS 超过 5000 个字符	询问用户拆分或截断
STT 超过 30 分钟	仅当请求的时长或资源成本尚未明确时进行确认
MCP 工具名称发生变化	重新运行 tools/list 并更新缓存
SIGINT	中止 MCP 调用，不写入部分输出
缺少本地媒体可执行文件	报告请求操作所缺少的工具；不要启动 Voicebox，也不要用占位内容替代音频
语音无法自然地适配	保留原始音频；在合成可用且获授权时调整生成语速，否则报告尚未解决的时间约束，不要截断词语

Exit

• 成功：音频文件或转录内容已生成，且包含完整清单，并已报告路径。
• 部分成功：输出已生成，但同时提示了防护措施警告（长度、磁盘、模型回退）。
• 失败：没有输出，并明确说明阻碍因素（身份验证、配置文件、引擎、网络）。

Logical Operations

操作

操作	SSL 原语	依据
验证模式和输入	VALIDATE	execution-protocol.md 中的澄清协议
解析 TTS 语音配置	SELECT	voicebox_list_profiles + 配置默认值
健康检查	READ	MCP 握手或 GET /health
生成语音	CALL_TOOL	MCP voicebox_speak
转录音频	CALL_TOOL	MCP voicebox_transcribe
写入输出和清单	WRITE	音频或转录文本，以及 manifest.json
检查结果	VALIDATE	输出是否存在、时长、清单字段
报告结果	NOTIFY	面向用户的最终摘要

工具和组件

• 用于生成／转录的 Voicebox MCP 服务，地址为 http://127.0.0.1:17493/mcp；处理现有音频时使用本地 FFmpeg 和 ffprobe。
• 用于健康检查和获取音频的 REST 接口（GET /health、GET /audio/{generation_id}）。
• 资源参考：语音矩阵、提示词技巧、执行协议、检查清单。

标准命令路径

将现有音频任务分派至 resources/audio-processing.md。以下路径仅适用于 Voicebox 生成／转录；定时 TTS 在获取原始 WAV 后，按照处理参考执行。

# 1. MCP handshake or REST health
GET http://127.0.0.1:17493/health  ->  200 OK

# 2. Discover tool names on first run
MCP tools/list                      ->  cache real names

# 3. TTS only: resolve profile
MCP voicebox_list_profiles          ->  pick profile by name or config default

# 4. Generate or transcribe (STT skips profile lookup and model-status check)
MCP voicebox_speak     { text, profile, language?, engine?, personality? }
MCP voicebox_transcribe { audio_path | audio_base64, language?, model? }

# 5. Fetch the generated audio (MCP has no save-to-disk; TTS output is wav)
GET http://127.0.0.1:17493/audio/{generation_id}  ->  wav bytes

# 6. Persist output + manifest
.agents/results/voice/<timestamp>-<shortid>/output.wav + manifest.json
.agents/results/voice/transcripts/<timestamp>-<shortid>/transcript.md + manifest.json

MCP 工具映射（经 Voicebox 0.5.0 验证）

用例	MCP 工具	REST 对应接口
TTS 生成	voicebox_speak	POST /speak
STT 转录	voicebox_transcribe	POST /transcribe
列出配置	voicebox_list_profiles	GET /profiles
列出录音	voicebox_list_captures	GET /history（录音视图）

未通过 MCP 暴露的工具（仅 REST）：模型状态（GET /models/status）、音频文件服务（GET /audio/{generation_id}）、各版本音频（GET /audio/version/{version_id}）。需要时，该技能会通过 loopback HTTP 调用这些接口。

关于 voicebox_speak 的说明：

• 必填：text。可选：profile、engine、language、personality（bool）。
• 音频会通过用户的扬声器播放，并自动保存到 Captures / History 面板。MCP 工具本身没有 save_to_disk 开关；如需保存本地副本，请获取 GET /audio/{generation_id}（Voicebox TTS 始终以 wav 格式存储）。
• 如果未在 Voicebox Settings 中设置默认配置，则必须提供 profile=。

关于 voicebox_transcribe 的说明：

• 必须且只能传入 audio_base64 或 audio_path（仅限 loopback）其中之一。可选：language、model。

资源范围

范围	资源目标
LOCAL_FS	输入音频、生成的音频、转录文本、清单
PROCESS	本地 Voicebox 应用（由用户管理）、FFmpeg／ffprobe 处理
NETWORK	仅限到 127.0.0.1:17493 的 loopback HTTP
MEMORY	缓存的 MCP 工具名称、已解析的配置元数据
CREDENTIALS	无。Voicebox 在本地运行，无需密钥。

前置条件

• 处理：本地 ffmpeg 和 ffprobe 能够读取源文件。
• 生成／转录：Voicebox 应用正在运行，且 MCP 握手成功。
• 仅限 TTS：至少存在一个语音配置。
• 仅限 TTS：所选引擎模型已加载，或用户批准下载。
• 除非明确允许，否则输出目录必须位于 $PWD 内。

影响和副作用

• 在 .agents/results/voice/ 下创建音频文件、转录文本和清单。
• 处理现有音频时会运行本地媒体子进程，并保留输入文件。
• 会触发本地 Voicebox 生成，消耗 CPU 或 GPU 资源。
• 用户批准后，可能会触发引擎模型下载。
• 不会调用任何云服务，也不会产生外部网络流量。

防护规则

1. Voicebox 模式：生成/转录需要完成 MCP 握手或请求 GET /health。如果失败，则退出并提供一次性的安装或启动提示；不要重试或自动重新启动。本地处理不需要 Voicebox。
2. 仅 TTS 需要配置档案：仅在通知或资源模式下解析配置档案并检查 TTS 引擎。即使没有配置档案，只要音频输入有效且可选的 STT 模型可用，转录仍可继续。
3. 工具名称发现：首次调用 Voicebox 时，调用 MCP tools/list 并缓存解析出的名称。同一会话中的后续调用复用该缓存。
4. 长度限制：每次 TTS 调用最多处理 5000 个字符；达到 2000 个字符时发出警告。STT 输入最长为 30 分钟。v1 不会自动分块或拆分。
5. 自动调用透明度：仅当当前任务超过 auto_notify_after_sec（默认 60 秒）时，才自动发送通知。该阈值是由 Agent 执行的指导原则——没有钩子会测量任务时长——因此应在长任务完成或受阻时自行判断是否适用。生成音频前，始终用一行简短说明告知用户。
6. 路径安全：用户明确指定的输出路径即表示授权写入该路径。在执行相关写入之前，先解决路径歧义或覆盖无关数据的问题；保留必需的 CLI 路径标志。
7. 取消：SIGINT 会中止 MCP 调用，且不会写入部分输出。
8. 持久化输出必须包含清单文件：资源 TTS 和转录模式会写入 manifest.json，至少包含：skill、mode、voicebox_generation_id、text（或 transcript_preview）、profile、engine、language、format（仅 TTS）、created_at。处理模式会按 resources/audio-processing.md 中的规定记录来源、操作和测得的输出属性；绝不会编造 Voicebox 来源信息。通知模式不受此要求约束，因为 Voicebox Captures 是其系统记录来源，且默认不会写入磁盘输出。
9. 不在范围内：故意不提供语音克隆 UI、捕获档案、故事编辑器、麦克风听写循环和云服务商。
10. 无费用限制：Voicebox 免费。oma-image 的费用防护规则不适用。

澄清流程

调用 TTS 或 STT 之前，Agent 会检查以下内容。如果缺少任何必需信息，应先向用户澄清。

TTS（资源模式）必需：

• 是否提供了文本内容？
• 是否提供了语音配置档案 ID 或音色描述？

强烈建议提供的 TTS 信息：

• 是否明确指定了语言，或能否从文本中检测出来？
• 是否指定了输出格式（默认 wav；mp3 需要在本地使用 ffmpeg 转码）？

STT 必需：

• 是否提供了音频路径，且文件存在？
• 时长是否在 30 分钟以内，或用户是否同意拆分？

**通知模式无需澄清。**它会使用配置中的 notification_profile，并自动检测消息语言。

调用

独立运行

/oma-voice "build succeeded, 4 minor warnings"
/oma-voice transcribe ~/Downloads/standup.m4a
/oma-voice --profile prof_warm_korean "다음 단계 진행 준비됐어요"

共享基础设施（其他技能）

其他技能可以直接调用相同的 MCP 工具来请求音频输出，也可以通过 /oma-voice 并附上文本来调用。没有单独的 CLI；该技能原生支持 MCP。

参考资料

• 语音引擎矩阵：resources/voice-matrix.md（TTS 配置文件／引擎选择）
• 提示词编写规则：resources/prompt-tips.md（TTS 文本）
• 执行协议：resources/execution-protocol.md（Voicebox 生成／转录）
• 现有音频和定时旁白：resources/audio-processing.md（处理、时长适配或按要求转换响度）
• 预检清单：resources/checklist.md（Voicebox 调用）
• 配置：先读取 .agents/oma-config.yaml 的 voice: 部分，然后对其中未设置的键回退使用 config/voice-config.yaml。两个配置文件的配置项初始值均为 null，必须按机器分别设置——请将配置写入 .agents/oma-config.yaml，因为 oma update 会覆盖技能配置。
• 上下文加载：references/_shared/core/context-loading.md
• 质量原则：references/_shared/core/quality-principles.md
• 设计参考：../../../docs/plans/designs/012-oma-voice.md（仅限源代码仓库；全局模式安装中不存在）