voicegen-port

voicegen-port

voicegen-port 通过 ElevenLabs API 将文本转换为语音，也能将音频转换回文本。它可以用选定的声音朗读一段文字，根据描述创作音效，转录录音，清理嘈杂片段并提取其中的人声，还能管理声音库本身——根据文字描述设计新声音，并保存值得留存的声音。它可通过命令行运行，也可作为供 Agent 使用的 MCP 服务运行。

此工具需要 ElevenLabs API 密钥。请将密钥放入 ELEVENLABS_API_KEY 环境变量；密钥会通过 xi-api-key 请求头发送到 API，绝不会出现在输出中。如果未设置该变量，每次调用都会失败，并显示指出该变量的错误。

音频是二进制数据，此工具会如实处理：生成调用会报告产物摘要（字节数、base64 长度、内容类型），而不是将原始音频倾倒到文本输出中。

安装

npx @reneturcios/voicegen-port voices

或者运行容器映像：

docker run -i -e ELEVENLABS_API_KEY ghcr.io/cloudcorprecords/voicegen-port

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

export ELEVENLABS_API_KEY="your ElevenLabs API key"

voicegen-port tts "Welcome to the show" --voice v_george
voicegen-port sfx "rain on a tin roof" --duration 4
voicegen-port stt interview.mp3 --language en
voicegen-port isolate noisy-call.mp3
voicegen-port voices
voicegen-port voice v_rachel
voicegen-port search-voices "narrator" --page-size 5
voicegen-port design "A calm British narrator" --text "Sample line"
voicegen-port create-from-preview gen_1 "Calm Narrator"
voicegen-port add-voice "Studio Voice" --description "Warm and close"
voicegen-port delete-voice v_old
voicegen-port models
voicegen-port subscription
voicegen-port user

voicegen-port --version

退出代码：成功时为 0，调用失败时为 1（包括缺少 ELEVENLABS_API_KEY 或 API 错误），用法错误时为 2。

MCP 服务

一个二进制文件同时提供两种用法。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/voicegen-port mcp

MCP 客户端配置：

{
  "mcpServers": {
    "voicegen-port": {
      "command": "npx",
      "args": ["-y", "@reneturcios/voicegen-port", "mcp"],
      "env": { "ELEVENLABS_API_KEY": "your ElevenLabs API key" }
    }
  }
}

工具

以下是官方 ElevenLabs MCP 服务中有文档说明的核心子集（14 个工具）。对话式 AI 和电话服务工具（create_agent、list_agents、get_agent、delete_agent、add_knowledge_base_to_agent、make_outbound_call、list_phone_numbers），以及 voice_clone、speech_to_speech 和 play_audio 尚未实现；请参阅构建报告。

工具	输入	返回内容
text_to_speech	text（必填）、voice_id、model_id、output_format（可选）	音频产物摘要：字节数、base64 长度、内容类型。
text_to_sound_effects	text（必填）、duration_seconds、prompt_influence（可选）	生成音效的音频产物摘要。
speech_to_text	file_path（必填）、language_code、model_id（可选）	转录内容，包括转录文本。
isolate_audio	file_path（必填）	分离出的人声轨道的音频产物摘要。
list_voices	—	所有声音：每个声音的 ID、名称和类别。
get_voice	voice_id（必填）	完整的声音记录。
search_voices	search（必填）、category、page_size（可选）	符合条件的声音，摘要格式与上述相同。
text_to_voice	prompt（必填）、text（可选）	声音设计预览，包括生成的声音 ID。
create_voice_from_preview	generated_voice_id、voice_name（必填）、voice_description（可选）	保存后的声音记录。
add_voice	name（必填）、description（可选）	添加的声音记录。
delete_voice	voice_id（必填）	API 的删除响应。
list_models	—	所有模型：每个模型的 ID、名称和描述。
check_subscription	—	账户的订阅记录。
get_user_info	—	API 密钥所有者的用户记录。

调用会向 https://api.elevenlabs.io/v1 发送 JSON 请求体。 speech_to_text 和 add_voice 在上游使用 multipart 上传；此重建版本将它们处理为 JSON 请求体，并在其中指定文件或声音。此简化做法已记录在构建报告中。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 详见 LICENSE。