debpalash/VoiceStudio

VoiceStudio 是做什么的？

使用用户正在运行的 VoiceStudio 后端。优先本地处理；远程工作者、云翻译、模型下载和外部集成需要用户选择。已安装的模型可以离线运行；不要保证每个配置的工作流都能离线运行。

连接与发现

默认后端地址为 http://localhost:3900；遵从用户配置的地址。Electron 的渲染器和开发代理是独立服务，不是公共后端 API。

1. 检查 GET /health。
2. 使用 GET /openapi.json 发现运行版本的契约，使用 GET /v1/audio/voices 发现语音和引擎。不要虚构配置文件 ID，也不要从目录列表中推断已安装的模型。
3. 如果后端不可用，启动已安装的应用。对于现有的源代码签出，请遵循其 Electron README（bun install、bun run setup:api，然后从仓库根目录 bun run dev）。不要安装第二个后端或覆盖现有的签出。
4. 本地配置可能允许未经身份验证的调用；受保护的部署需要配置的凭据。将 401/403 视为身份验证失败，而不是禁用身份验证的权限。切勿打印令牌或使用占位符密钥作为真实凭据。

生成语音

将此 JSON 保存到 speech-request.json，当用户选择了语音时，将 voice 替换为发现的配置文件 ID：

{"model":"tts-1","voice":"alloy","input":"每个声音都有一个故事。让我们讲述你的故事。","response_format":"wav"}

curl --fail-with-body --show-error http://localhost:3900/v1/audio/speech \
  -H 'Content-Type: application/json' --data-binary @speech-request.json \
  --output speech.wav

tts-1 和 ts-1-hd 是别名，不是质量保证。OpenAI 语音名称是兼容性别名，不是这些提供者的实际语音。优先使用发现的已保存语音进行可重复的叙述。在承诺结果之前，请检查已安装引擎的语言和语音设计能力。

检查 HTTP 状态并解码/探测输出，然后再将其称为音频：错误响应可能会写入输出路径。报告保存的路径和实际持续时间/格式。切勿虚构成功的生成、转录或作业完成。

转录

curl --fail-with-body --show-error http://localhost:3900/v1/audio/transcriptions \
  -F [email protected] -F model=whisper-1 -F response_format=verbose_json

对于纯文本转录使用 json 或 text，对于带时间戳的使用 verbose_json，对于受运行模式支持的副标题使用 srt/vtt。在长录音之前检查转录模型的就绪状态；解释缺失的模型并获取下载授权，而不是静默安装它。

克隆、设计、配音和更长的工作流

使用已安装的 OpenAPI 模式发现配置文件创建、参考上传、生成、配音和长格式作业操作。它们的原生端点比 OpenAI 兼容 API 更广泛，并且独立演进。

• 仅克隆用户有权使用的语音。保留参考文件和现有配置文件。
• 对于设计，捕获所需的语气、表达方式、语言和示例文本；检查引擎支持。
• 对于配音，保留原始媒体、说话人分配、片段时间轴和背景音频意图。翻译完成不等于配音渲染完成。
• 对于异步工作，使用返回的作业 ID 和记录的进度/状态端点。检查终端错误；避免盲目重新提交超时的生成。
• 返回可用的文件和诚实的限制，包括缺失的模型或不可用的功能。

MCP 和自动化

运行中的后端在 http://localhost:3900/mcp 挂载一个 MCP 端点。使用客户端支持的 HTTP 传输并在运行时发现其工具。重用现有连接，而不是启动另一个服务。对于仅 stdio 的客户端，请查阅项目的 MCP 指南 获取其 shim。

对于 n8n、调用代理、容器或其他主机，使后端地址可从该环境访问：容器 localhost 指的是容器本身。保持身份验证和显式远程路由选择不变。集成目录列表并不意味着集成已连接。

出错时，读取响应体，区分后端不可用、模型缺失、功能不支持、身份验证失败和硬件繁忙。修复报告的条件；不要切换到托管提供商或未经授权下载模型。

桌面工作流和就绪性

Electron 应用包括语音克隆和设计、已保存的配置文件和库、故事/有声书、配音项目、转录、工具和集成。优先使用其现有的项目和语音标识符，而不是创建重复项。对于桌面自动化，检查实际的 UI 和当前设置快捷方式；不要假设快捷方式绑定或麦克风权限在每个主机上都相同。

在进行听写之前，验证已安装的语音转文本模型和可用的输入设备。区分录音、暂停录音、转录处理和完成的文本。将转录内容复制并插入到另一个应用中是不同的操作；在键入之前确认目标应用，并在支持的情况下保留剪贴板内容。切勿仅仅因为转录完成就报告文本已交付。

对于配音，在导出之前检查缺失/失败的片段和时间轴溢出。在要求时保留音乐和非语音音频；不要静默替换整个音轨。保留源文件并将输出作为单独的人工制品。翻译风格提示属于所选的翻译操作，远程代理翻译需要用户配置的提供商选择。

使用集成目录作为发现和设置指南，而不是工作连接器的证明。在将连接描述为就绪之前，验证实际凭据、端点可达性和支持的操作。容器部署需要持久数据卷和调用客户端可访问的后端 URL。