yovoice CLI
Local speech synthesis for agents: a command and a skill voice text, clone a voice from a recording and render scores to audio, with no cloud
- 1,968 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Downloads an engine and gigabyte-sized models from the network and runs them on your computer
- Reads your voice recordings and writes audio and data to `~/.yovoice`
- The `yovoice serve --listen 0.0.0.0:8080` mode opens the service to the network, and one shared token gives access to all saved voices and audio
Install
- Works in
Manual install
yovoice setupDownloads the audio.cpp v0.9.1 engine: Metal on Mac, CPU on Windows and Linux. Pick another with `--backend`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Downloads an engine and gigabyte-sized models from the network and runs them on your computer
- Reads your voice recordings and writes audio and data to `~/.yovoice`
- The `yovoice serve --listen 0.0.0.0:8080` mode opens the service to the network, and one shared token gives access to all saved voices and audio
This is third-party code. Review the repository files before installing.
What it does
yovoice is an open-source local audio and music studio, and for agents it ships a standalone `yovoice` command and a `skills/yovoice` skill. The command runs without the desktop app on macOS with Apple Silicon, Windows x64 and Linux x64. `yovoice setup` downloads the audio.cpp v0.9.1 engine, `yovoice models download` installs the chosen model, and `yovoice generate` turns text from `--text` or `--text-file` into a WAV file. The voice comes from a reference recording (`--reference`, 1 to 60 seconds, up to 20 MB) or a saved voice (`--voice`); some models can also design a voice from a text description and carry built-in voices. The skill teaches the agent the order of work: check `yovoice --help` and `yovoice status --json`, learn the real model and voice IDs through `yovoice models list --json` and `yovoice voices list --json`, put long text into a UTF-8 file and start generation. The result arrives as a JSON line on standard output with an absolute path and duration, and progress goes to the error stream. The skill text is written in Chinese. The agent gets the same abilities over MCP: `yovoice mcp` starts as a subprocess over stdio, and `yovoice serve` brings up an HTTP API and MCP service for other machines with a token of at least 32 characters. A separate `yovoice score render` command builds music from a JSON score or MIDI with a General MIDI sound font and saves the mix and the individual tracks.
Who it is for. For developers and content authors who need to voice a text, produce a narration or background music from an agent without sending texts and voice recordings to a cloud service.
Good fit when
- An agent has to voice an article or script from a text file with a voice taken from a reference recording
- You need a voice from a verbal description with no reference recording (VoxCPM2 and Qwen3-TTS VoiceDesign models)
- Notes have to become background music: a JSON score or MIDI turns into WAV and separate tracks
- Generation has to move to another machine with a GPU, with the agent connecting over HTTP or MCP
Not a fit when
- You need real-time streaming speech: every model first produces the whole file, and there is no streaming mode
- You need songs with lyrics through the `generate` command: the ACE-Step and YuE2 music models run only in the desktop app
- The computer does not fit: macOS on Apple Silicon, Windows x64 and Linux x64 are supported, and there is no Linux ARM64 package
- You want to plug in your own model: only the models yovoice lists can be installed, and importing a local GGUF is not supported
Example request
Voice the text in narration.txt with the voice from voice.wav, in a calm tone, and save the result as narration.wavLimitations
- The Apache-2.0 license covers the code, while models carry their own terms: OmniVoice, YuE2 and Breeze TTS 2 weights are limited to non-commercial use, and OmniVoice is released under CC-BY-NC. Clone only voices you have permission to use.
- The `~/.yovoice` data directory is held by one app, one command or one server at a time; with the app open, use `--data-dir` or its local API. The server runs one upload or generation at a time, answers 409 when busy with no queue, and keeps records of the latest 100 tasks in memory only.
- Output is saved as WAV only and never overwrites an existing file; every `generate` command reloads the model.
- Models take from 1.35 to 8.08 GB and download from ModelScope by default, with `--source huggingface` and `--source mirror` as separate options. On Windows and Linux the engine runs on the CPU by default, and GPUs need compatible drivers.
- The author does not promise a fixed result: emotion depends on the model, the text and the reference. The skill asks the agent not to claim verified quality until the audio has been listened to.
How to disable. The documentation has no uninstall command. Remove the skill folder from the agent's skill directory and the `yovoice` entry from the MCP settings, then delete the folder the command archive was extracted to and its PATH entry. Models, voices and audio stay in `~/.yovoice` and are removed by hand.
FAQ
Do I need the desktop app to voice text from an agent?
No. The `yovoice` command is standalone, the archive includes an audio converter, so separate FFmpeg, Python and Go are not needed. The engine and models download separately with `yovoice setup` and `yovoice models download`.
Which recordings work as a voice reference?
Ones from 1 to 60 seconds long and up to 20 MB. WAV, MP3, M4A/AAC, FLAC, OGG/Opus, AIFF, WMA and WebM are accepted and converted automatically. You can save a voice with `yovoice voices import voice.wav --name Narrator` and then use it through `--voice`.
Can yovoice speak Russian?
For Qwen3-TTS models the language option accepts ru, and VoxCPM2 detects the language from the text among the 30 it supports. IndexTTS 2.5 lists Chinese, English, Japanese, Spanish and Arabic, and Russian is not on that list.
How do I connect yovoice to Claude Code or Cursor as an MCP server?
Add `{"mcpServers": {"yovoice": {"command": "yovoice", "args": ["mcp"]}}}` to the MCP settings. The client starts the subprocess over stdio itself, with no token or port. If the executable is not on PATH, give the full path.
What does `yovoice serve` do and how do I protect it?
The command brings up an HTTP API and MCP on `127.0.0.1:8080` by default. The token comes from the `YOVOICE_API_TOKEN` variable and must be at least 32 characters. Outside a trusted network turn on HTTPS with `--tls-cert` and `--tls-key`. The request reference is served at `/docs/` on the running server.
Can the generate command produce a song?
No. ACE-Step and YuE2 run only in the desktop app, and `generate` does not support them. For music on the command line there is `yovoice score render`, which renders a score through the `musescore-general-sf2` sound font.
Discussion
No questions or reviews yet.
Related
CLI toolsTen skills from ElevenLabs: text to speech, transcription, voice agents, sound effects, music, dubbing and voice cleanup through the API
A skill that teaches the agent to build narrated videos through narrator-ai-cli: source, template, music, voice, script and composing
An MCP server for Sber's SaluteSpeech voice API: records speech from the microphone, recognizes it and speaks the agent's reply
A skill that writes prompts for video, image and music generation on 14 platforms and can submit them in the browser
Skills, a CLI and an MCP server that let Claude Code or Codex make video from a brief: editing, graphics, voiceover, subtitles
A skill for Cursor, Claude Code and Codex: from a product name or URL it builds a 4K promo with music, voice-over and checks
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| yovoice (this entry) | no | 1,968 | ||
| VoiceMode | yes | not required | 1,427 | voice conversation with Claude Code: speech recognition and synthesis, local or through the cloud |
| ElevenLabs Skills | yes | 516 | voice-over, transcription and music through the ElevenLabs cloud API | |
| MCP SaluteSpeech | yes | API key | 9 | an MCP server for Sber's cloud SaluteSpeech voice API |
README in short
The repository holds the desktop app (the `desktop` and `web` folders), a Go service (`cmd` and `internal`), the `skills/yovoice` skill with references on models, audio, scores and remote access, documentation for the command, the API, models, scores and development, a changelog and a list of third-party licenses. The description, in English and Chinese, lists the features, a model table, install packages for macOS and Windows and a sample prompt for an agent.
README badge
Original SKILL.md
--- name: yovoice description: 使用 yovoice 本地 CLI 或远程 HTTP API／MCP 生成语音，用于配音、旁白、朗读、声音设计和音色克隆；也可写乐谱渲染配乐。无需桌面 App。 --- # yovoice 配音 ## 选择运行方式 - 用户指定远程服务或已有可用的 yovoice MCP 连接时，优先复用该服务，阅读[远程调用参考](references/remote.md)。客户端无需安装 CLI、引擎或模型。 - 使用本地推理时，按下方流程准备 CLI。用户明确选择的运行方式优先；远程连接失败时先核对地址和认证，不擅自改用本地或安装模型。 - 模型与音色 ID 来自所选服务或本地实例，不能跨实例直接复用。 ## 本地 CLI 使用 `yovoice --help` 检查命令是否可用，再运行 `yovoice status --json`。CLI 独立运行，无需安装桌面应用或开发环境。 ## 安装 CLI 命令不可用时，从 [GitHub Releases](https://github.com/leemysw/yovoice/releases) 下载对应平台的独立 CLI 压缩包。文件名中的 `<版本>` 为 Release 标签，例如 `v0.1.0`。 | 平台 | 安装包 | 可执行文件 | | --- | --- | --- | | macOS · Apple Silicon | `yovoice-<版本>-cli-macos-arm64.zip` | `yovoice` | | Windows · x64 | `yovoice-<版本>-cli-windows-x64.zip` | `yovoice.exe` | | Linux · x64 | `yovoice-<版本>-cli-linux-x64.zip` | `yovoice` | 完整解压并保留同级 `tools/` 目录，将可执行文件所在目录加入用户 PATH，重新启动 Agent，再执行 `yovoice --version` 验证安装。也可通过可执行文件的绝对路径调用。压缩包包含本 Skill；安装 Skill 不会自动安装 CLI、引擎或模型。 ## 准备 - 仅支持 Apple Silicon macOS、Windows x64 和 Linux x64。所有命令的选项放在命令及位置参数之后。 - 默认数据目录与 App 相同（`~/.yovoice`，App 中迁移过则为迁移后的位置）。如果被 App 或另一个 CLI 占用，不终止用户任务；使用用户指定的独立 `--data-dir`，所有后续命令保持同一路径。新目录需要独立准备运行时和登记模型。 - `yovoice models list --json` 查看真实模型 ID 和安装状态；`yovoice voices list --json` 查看可用音色 ID。 - 安装引擎、选择 CPU/GPU、下载或登记模型时，阅读[引擎与模型参考](references/setup.md)。 - 用户提供参考文件时用 `--reference`。常见音频格式内部自动转换；格式、时长限制和复用方式见[音频参考](references/audio.md)。IndexTTS 需要参考音色；VoxCPM2 可无需参考音频进行声音设计，模式与参数见同一参考文档。 - 选择模型变体、内置音色、设计属性或高级生成参数时，阅读[模型能力参考](references/models.md)。Qwen Base、CustomVoice、VoiceDesign 的输入不同，不混用参考音频、内置说话人和设计描述。 ## 生成 把长正文写入 UTF-8 文件，避免 shell 转义和命令行长度问题。例如： ```sh yovoice generate --text-file narration.txt --reference voice.wav --model index-2.5-q8 --language zh --speed 1 --output narration.wav --json ``` 已有音色改用 `--voice ID`，与 `--reference` 互斥。IndexTTS 需要情绪指导时添加 `--emotion-text "温柔、平静"`；效果受模型、文本和参考音频影响，不承诺固定效果。仅在用户需要时调节参数，默认沿用参考音色。不要使用不存在的预设参数。 命令阻塞到完成，进度在 stderr，stdout 只有最终 JSON；失败返回非零退出码，错误 JSON 在 stderr。Ctrl-C 取消当前命令并清理引擎，不提供跨进程取消命令。不要因首次模型加载慢反复启动任务。 成功后使用 JSON 的绝对 `path` 和 `duration` 交付音频；能够播放时展示播放器。没有实际试听，不宣称音质验证通过。参数错误先修正，下载或推理失败保留错误和日志线索，不无条件循环重试。输出文件默认拒绝覆盖，重新生成使用新文件名。 ## 编曲配乐 用户需要配乐、垫底音乐或把 MIDI 渲染为音频时，阅读[编曲参考](references/score.md)：写乐谱 JSON，用 `yovoice score render` 渲染混音和分轨。