# 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.