happy-audio-gen

Q: How do I install happy-audio-gen?

Run npx skills add https://github.com/iamzhihuix/happy-claude-skills --skill happy-audio-gen in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/happy-audio-gen/ (personal) or .claude/skills/happy-audio-gen/ (project).

by iamzhihuixMedia & Creative

Universal AI voice / text-to-speech skill supporting OpenAI TTS (gpt-4o-mini-tts, tts-1), ElevenLabs multilingual TTS with voice cloning, Bailian Qwen TTS (qwen-tts / qwen3-tts-vd with voice-design custom voices, long-text chunking built in), MiniMax speech-02-hd, SiliconFlow CosyVoice / SenseVoice, and PlayHT 2.0. Use this skill whenever the user asks to read text aloud, synthesize speech, generate narration, create voice-over, dub a script, or turn any text into audio (mp3 / wav / ogg / flac). Typical phrases include "read this aloud", "generate voice for ...", "create a narration of ...", "tts this", "把这段念出来", "做个配音", "合成语音", or mentions of voices / TTS model names like Alloy, Ash, Cherry, Rachel, CosyVoice, PlayHT. Always use this skill even if the user does not specify a provider — pick one from EXTEND.md defaults or available env keys.

Installs: 146
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/iamzhihuix/happy-claude-skills --skill happy-audio-gen

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads happy-audio-gen automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

happy-audio-gen

Turns text into speech across 6 providers through one CLI. All providers are synchronous (TTS is fast — typically under 10 seconds) except Bailian's voice-design flow (which is still covered but uses a longer poll window).

Quick usage

# Shortest path — OpenAI default voice
bun scripts/main.ts --text "Hello, world" --out ./hello.mp3

# Chinese, MiniMax
bun scripts/main.ts --provider minimax --text "大家好" --voice male-qn-qingse --out ./hello.mp3

# Long-form, Bailian (auto-splits by sentence)
bun scripts/main.ts --provider bailian --textfiles ./script.md --out ./narration.mp3

When to invoke this skill

User asks to synthesize speech / TTS / read aloud / narrate / dub / make a voice-over.
User asks to convert script / text / article into audio.
User names a TTS voice or model.

Do not route here when the user wants to transcribe audio → text (that's STT, different domain), or edit / mix audio files (use a dedicated audio editor).

Step 0: Preflight (BLOCKING)

Locate EXTEND.md:
- ./.happy-skills/happy-audio-gen/EXTEND.md
- $XDG_CONFIG_HOME/happy-skills/happy-audio-gen/EXTEND.md
- ~/.happy-skills/happy-audio-gen/EXTEND.md
If none found, run bun scripts/main.ts --setup and walk the user through references/config/first-time-setup.md.
Verify at least one provider has credentials (env var or 1Password reference).
Verify Bun is available. Fallback: npx -y bun.

Step 1: Choose provider

Preference order:

--provider <id>
EXTEND.md default_provider
Auto-detect env vars: openai > elevenlabs > bailian > minimax > siliconflow > playht

Pick by language / voice intent:

English, natural + fast → openai (gpt-4o-mini-tts / tts-1).
Multilingual, voice cloning → elevenlabs.
Chinese, long-form → bailian (qwen-tts auto-chunks long scripts) or minimax.
Chinese dialect / voice design → bailian (voice-design with qwen3-tts-vd) or siliconflow (CosyVoice2).
Ultra-realistic, short-form → playht (2.0).

Step 2: Fill parameters

--text or --textfiles: input. Always quote.
--out <path>: REQUIRED. Extension determines format (.mp3 / .wav / .ogg / .flac).
--voice <id>: provider-specific. See references/voices.md for the short list of well-known voices.
--rate 0.5..2.0: speaking rate.
--instruction "...": voice direction (only openai gpt-4o-mini-tts and siliconflow honor this).
--language <code>: en, zh, ja — only a few providers honor this explicitly.

Step 3: Run

bun scripts/main.ts \
  --provider openai \
  --model gpt-4o-mini-tts \
  --voice alloy \
  --text "..." \
  --out ./out.mp3

JSON mode:

{ "success": true, "provider": "openai", "model": "gpt-4o-mini-tts", "voice": "alloy", "output": "/abs/out.mp3", "size_bytes": 76032, "format": "mp3" }

Step 4: Long text handling

happy-audio-gen automatically splits long input for providers that cap per-call length (Bailian ≤ 200 Chinese chars per call). Chunks are concatenated byte-for-byte on output.
For best fidelity with concatenated MP3s, stitch the segments with ffmpeg afterward rather than relying on byte concat.

Step 5: Errors

[openai] OpenAI TTS 400 with invalid voice → the voice name is not supported by the model. Use one of alloy, ash, coral, echo, fable, onyx, nova, sage, shimmer.
[minimax] ... 2049 invalid api key → try MINIMAX_BASE_URL=https://api.minimaxi.com/v1 (different region).
[bailian] ... 400 DataInspectionFailed → Aliyun content filter. Surface to the user.
[elevenlabs] 401 → key invalid or subscription expired.

References

references/providers.md — per-provider env vars, default models, voice lists.
references/voices.md — curated voices for each provider.
references/error_codes.md — common errors and fixes.
references/config/first-time-setup.md
references/config/extend-schema.md
assets/EXTEND.template.md

FAQ

What does the happy-audio-gen skill do?

How do I install happy-audio-gen?

Run npx skills add https://github.com/iamzhihuix/happy-claude-skills --skill happy-audio-gen in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/happy-audio-gen/ (personal) or .claude/skills/happy-audio-gen/ (project).

Which AI agents can use happy-audio-gen?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is happy-audio-gen safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains happy-audio-gen?

It is published by iamzhihuix in iamzhihuix/happy-claude-skills. It has 146 recorded installs.