# Batch Audio Workflows

Use this reference for directory-scale ASR, clone, and export jobs such as game filter alert sounds.

## Pick The Output Mode First

Clarify or infer the output mode before generating many files:

- **Generated-only assets**: create cloned speech files named after the source audio. This is the safest default when the user wants files they can manually replace elsewhere.
- **Overlay/mix**: mix generated speech with the source audio only when the user explicitly asks for overlay.
- **Speech replacement inside mixed audio**: do not promise clean removal from mixed music/SFX using ASR timestamps alone. Clean replacement requires source separation, stems, or a dedicated vocal-removal model.

If the user says the old and new voices are both audible, stop overlay work and export generated-only assets instead unless they ask for source separation.

## Generated-Only Batch Export

Prefer the bundled script:

```bash
python ~/.codex/skills/eapil-voice/scripts/batch_clone_generated_audio.py \
  --base-url https://ades.playones.com \
  --token "$OPENAI_API_KEY" \
  --input-dir "/path/to/source-audio" \
  --reference-audio reference.wav \
  --output-dir "/path/to/generated-output" \
  --format mp3 \
  --gain-db 4 \
  --overwrite
```

The script:

- ASRs each source file.
- Normalizes alert text punctuation.
- Uses the reference audio stem as `ref_text`.
- Calls `/v1/voice/clone` with `provider=qwen` by default.
- Saves `_raw_wav/` originals plus final WAV/MP3 named after the source files.
- Writes `_manifests/` and `conversion_summary.json`.

If `OPENAI_API_KEY` is not set, ask the user to get their key from `https://kinfo.playones.com` or pass the key directly with `--token`.

## Text And Punctuation

For Chinese alert text, normalize whitespace and punctuation before clone. Add expressive punctuation when it matches the phrase. If the final character is not one of `。！？.!?~～`, append `。`.

## Gain And Format

Service clone responses are WAV. For MP3 delivery, use ffmpeg after generation:

```bash
ffmpeg -y -i generated.wav -filter:a "volume=4dB" -codec:a libmp3lame -q:a 2 generated.mp3
```

Use the user's requested gain literally. Do not normalize or limit unless requested.

## Windows Notes

Paths with spaces or CJK characters are common. Prefer direct shell invocation. If launching a background job with PowerShell `Start-Process`, pass a single fully quoted `-ArgumentList` string; arrays can be split incorrectly.

Use `subprocess.run(..., encoding="utf-8", errors="replace")` in Python when capturing ffmpeg output on Windows to avoid GBK decode crashes.
