118 lines
3.8 KiB
Markdown
118 lines
3.8 KiB
Markdown
# voice-generation
|
|
|
|
Batch text-to-speech via the `mmx` CLI, with a local registry of custom MiniMax voice clones.
|
|
|
|
This vault Skill is named `voice-generation`. The Python package, module, and command remain:
|
|
|
|
```text
|
|
package: voice-gen
|
|
module: voice_gen
|
|
command: voice-gen
|
|
```
|
|
|
|
## Install
|
|
|
|
See [INSTALL.md](INSTALL.md) for the current `skills-vault` installation workflow.
|
|
|
|
Short version from the repository root:
|
|
|
|
```powershell
|
|
conda env create -f environment.yml
|
|
conda activate skills-vault
|
|
|
|
pip install -e .\skills\voice-generation
|
|
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\install-skill.ps1 -Skill voice-generation -Force -InstallClaudeLink
|
|
```
|
|
|
|
External requirements:
|
|
|
|
- Conda
|
|
- `mmx` CLI v1.0.16+ (`npm.cmd install -g mmx-cli` on Windows)
|
|
- `cmd /c mmx auth login` once on Windows
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Initialize a project
|
|
voice-gen init
|
|
|
|
# 2. Register a custom voice
|
|
voice-gen voices add ./samples/wantsong.mp3
|
|
|
|
# 2b. Or pull existing voices from the server
|
|
voice-gen voices pull
|
|
|
|
# 3. Put Markdown scripts in scripts/
|
|
echo "Hello, this is a test." > scripts/hello.md
|
|
|
|
# 4. Generate audio
|
|
voice-gen gen --voice wantsong scripts
|
|
# -> output/hello.mp3
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Purpose |
|
|
| --- | --- |
|
|
| `voice-gen init` | Create `voices.json`, `scripts/`, and `output/` in the current working directory. |
|
|
| `voice-gen voices add <audio>` | Upload audio; friendly name is derived from the filename stem. |
|
|
| `voice-gen voices list [local\|server]` | List voices. Default scope is `local`; `server` queries MiniMax files. |
|
|
| `voice-gen voices pull [--auto] [--force] [--dry-run]` | Sync server-side voices into the local registry. |
|
|
| `voice-gen voices cleanup` | Dedupe by source filename, keeping the oldest. |
|
|
| `voice-gen gen --voice <name> <input-dir> [--out DIR] [--format mp3\|wav\|flac\|pcm\|opus]` | Batch synthesize Markdown scripts. |
|
|
|
|
## How It Works
|
|
|
|
The CLI wraps MiniMax voice operations:
|
|
|
|
- Voice audio is uploaded with a direct MiniMax file upload call.
|
|
- Uploaded files are registered through the MiniMax voice clone API.
|
|
- Synthesis uses `mmx speech synthesize`.
|
|
|
|
On Windows, `mmx` is a `.cmd` shim from npm, so subprocess calls are routed through `cmd /c` where needed. Synthesis text is written to a short-lived UTF-8 file next to the requested output and passed with `--text-file`; the file is removed after each call. This avoids Windows command-line length and quoting limits. It also avoids mmx-cli's current `--text-file -` stdin implementation, which resolves `/dev/stdin` as a drive-local path on Windows.
|
|
|
|
CLI status lines escape non-ASCII path characters as ASCII `\uXXXX` sequences so `conda run` remains safe on GBK Windows consoles. The files themselves retain their original Unicode names.
|
|
|
|
## Project Layout
|
|
|
|
```text
|
|
skills/voice-generation/
|
|
SKILL.md
|
|
INSTALL.md
|
|
pyproject.toml
|
|
src/voice_gen/
|
|
tests/
|
|
docs/examples/
|
|
```
|
|
|
|
Runtime project files are created where the user runs `voice-gen init`:
|
|
|
|
```text
|
|
voices.json
|
|
scripts/
|
|
output/
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# From the repository root
|
|
conda run -n skills-vault python -B -m pytest skills/voice-generation/tests -p no:cacheprovider --basetemp tmp/pytest-voice-generation
|
|
|
|
# Smoke tests may call real MiniMax services and consume quota.
|
|
conda run -n skills-vault python -B -m pytest skills/voice-generation/tests --run-smoke -p no:cacheprovider --basetemp tmp/pytest-voice-generation-smoke
|
|
```
|
|
|
|
The test configuration forces imports from this repository's `src` tree so a separately installed `.agents/skills` copy cannot make source tests pass accidentally.
|
|
|
|
## As An Agentic Skill
|
|
|
|
The root `SKILL.md` exposes this tool to Agentic systems. The public installed Skill path is:
|
|
|
|
```text
|
|
C:\Users\wangq\.agents\skills\voice-generation
|
|
```
|
|
|
|
Claude and other private Skill folders may link to that public installation path.
|