Content & Media Creation · daymade/claude-code-skills

stepfun-tts

Name: stepfun-tts
Author: daymade/claude-code-skills

Generate Chinese / Japanese speech with StepFun's stepaudio-2.5-tts — Contextual TTS that replaces step-tts-2's `voice_label` with natural-language `instruction` (≤200 chars) plus inline `()` parentheses for句内 prosody. Use when the user wants emotional / prosody control over voice synthesis (whisper, pause, stress, mood pivot mid-sentence), batch-generates game / app voice lines, migrates from `step-tts-2` (the `voice_label → instruction` breaking change), or hits StepFun's stricter 2.5-era censorship (死/消失/political terms). Triggers on 阶跃 TTS, StepAudio 合成, 语音合成, 配音, 文本转语音, TTS 升级, 迁移 step-tts-2. For transcription with the sibling stepaudio-2.5-asr model, use the stepfun-asr skill instead.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The core knowledge centers on two major changes in the 2.5 era: voice_label is no longer accepted (replaced by natural-language instruction ≤200 characters + inline () prosody instructions within the text), and censorship is stricter (words like 死/消失/sensitive political terms trigger censorship_block).

daymade-audio/stepfun-tts/SKILL.md

**What `stepaudio-2.5-tts` will NOT accept** — `voice_label` parameter. Error: `voice_label is not supported for v2 models`. This is the #1 migration gotcha from step-tts-2.

What is happening here: The 'two costliest pitfalls during migration' are addressed upfront—raw error messages are translated by scripts into actionable hints ('HINT: stepaudio-2.5-tts does not accept voice_label. Put emotion/prosody into `instruction`…'), with the censorship vocabulary list and rewriting strategies documented in references/migration_from_v2.md.

The script sends a request to /v1/audio/speech: JSON body (model/input/voice/response_format/speed/volume + optional instruction), Authorization Bearer, and directly writes the mp3 bytes to disk upon success.

daymade-audio/stepfun-tts/scripts/tts_generate.py

body: dict[str, Any] = { "model": MODEL, "input": text, "voice": voice, "response_format": response_format, "speed": speed, "volume": volume, }

API_URL = "https://api.stepfun.com/v1/audio/speech", MODEL = "stepaudio-2.5-tts", DEFAULT_VOICE = "shuangkuaijiejie"; when instruction is present, it validates that length is ≤200 characters (returns an error without initiating the request if exceeded).

Hard validation on instruction length + inline () prosody passed via text: Bracketed contents within the sentence, such as (试探着问)/(轻声)/(停顿一下), are consumed by the model as performance directions rather than read aloud.

daymade-audio/stepfun-tts/scripts/tts_generate.py

if instruction: if len(instruction) > 200: return {"ok": False, "status": 0, "err": f"instruction too long: {len(instruction)} > 200 chars"}

SKILL.md provides verified examples: instruction '活泼俏皮，像是在撒娇，带点嘴硬' noticeably accelerates speech rate, while '耳语声，气声很重' produces breathy whispering; input '你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。' successfully applies all inline instructions.

Line-by-line fallback for censorship_block: Detects 'censorship_block'/'blocked' to mark failed lines; batch mode logs skipped IDs and proceeds without interrupting the entire batch.

daymade-audio/stepfun-tts/scripts/tts_generate.py

censored = "censorship_block" in raw or "blocked" in raw.lower()

In the batch loop, censored lines are appended to the censored list while other failures go to the failed list, followed by a summary output at the end; SKILL.md recommends hybrid model fallback (falling back to step-tts-2 for that line is standard practice).

Batch processing: --batch reads JSONL ({id, text, instruction?} one object per line) and synthesizes line by line into --out-dir/<id>.mp3, sleeping delay-ms between lines to avoid rate limits.

daymade-audio/stepfun-tts/scripts/tts_generate.py

out_path = args.out_dir / f"{line_id}.mp3" if result["ok"]: out_path.write_bytes(result["audio_bytes"])

read_batch skips empty lines and # comment lines; each line can override voice/speed/volume. When main() completes, it returns 0/1 depending on whether the failed list is empty, with censored items counted separately.

Non-destructive A/B testing is a design invariant: Regenerated voice lines are written to a parallel directory (voice/zh_v25/) without ever overwriting production assets; ab_compare.sh uses ffprobe/stat to compare mp3 file size and duration across both directories, outputting a markdown table.

daymade-audio/stepfun-tts/SKILL.md

1. **Non-destructive A/B output** — when regenerating a corpus with a new model, write to a parallel directory (`voice/zh_v25/`), never overwrite the production corpus.

Header comment of ab_compare.sh states 'compare two directories of mp3 files (size + duration)'; it only compares files present in both directories while listing exclusive files separately, supporting dual compatibility for ffprobe and GNU/BSD stat.

2Core Capabilities

01Single-sentence synthesis (--text/--out/--instruction/--voice/--speed/--volume)

02Synthesis for 1-1000 Chinese/Japanese characters with semantic boundary splitting guidance for the hard 1000-character ceiling

03Batch voice line synthesis (--batch jsonl + line-by-line censorship fallback + inter-line delay for rate-limit prevention)

04Emotion/prosody control: Global instruction + intra-sentence () bracket directions

05step-tts-2 → 2.5 migration guide (INSTRUCTION_MAP/SKIP_CENSORED/output directory strategies)

06Dual-model A/B comparison (ab_compare.sh: ffprobe duration + stat bytes + Δ% markdown table)

07Censorship rewriting/fallback guidance (死/消失/political terms → rewrite or fall back to step-tts-2 for that line)

3External Dependencies

Kind	Dependency / Endpoint
network	api.stepfun.com（StepAudio TTS 端点）
network	platform.stepfun.com（取 key/定价/voice 文档，仅指引）
cli	python3（stdlib urllib，无第三方包）
cli	ffprobe（ffmpeg，ab_compare 用）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local script or command: daymade-audio/stepfun-tts/scripts/tts_generate.py
网络端点: Declared external network access: POST https://api.stepfun.com/v1/audio/speech (request body containing text to synthesize + instruction + Auth)
本地工作目录: File read/write and artifact output: tts_generate.py writes --out (single line) or --out-dir/<id>.mp3 (batch, mkdir parents) to user-specified paths

Audit Notes: Classified per unified criteria: Accessing plaintext API credentials ($STEPFUN_API_KEY / ${CLAUDE_PLUGIN_DATA}/config.json) warrants an Orange tier; it also involves outbound network traffic (text payloads POSTed to the official api.stepfun.com TTS endpoint). Writing local mp3s follows user-designated outputs with no destructive actions. Similar to stepfun-asr: Key access surface + outbound data transmission to third parties results in Orange.

5Second-Pass Verification

[ok] 端点/body/模型名（/v1/audio/speech + stepaudio-2.5-tts） — tts_generate.py API_URL/MODEL 常量与 body dict 逐字存在；api_reference.md 同。
[ok] voice_label 拒绝处理（迁移 gotcha） — 脚本对 raw 含 'voice_label is not supported' 时追加 HINT 文案；SKILL.md 错误表同描述。
[ok] instruction ≤200 硬校验 — synthesize() 内 'if len(instruction) > 200: return {ok: False, status: 0, err: ...}' 存在，超长不发请求。
[ok] censorship 逐行降级（不整批失败） — censored 列表单独收集、failed 汇总、循环 continue；main 返回码只按 failed 定。
[ok] API key 解析（env → CLAUDE_PLUGIN_DATA/config.json） — load_api_key 顺序与 asr 版一致（env 优先、config 兜底、fail-fast）。
[ok] A/B 脚本无网络、本地文件对比 — ab_compare.sh 仅 comm/stat/ffprobe；--noproxy/网络 token 零命中。
[ok] 功能声明 vs 夸大检查（voice cloning 未验证声明） — known_issues.md 第 56 行明确 'Zero-shot voice cloning (9.9 元/音色) … was not verified in this skill's test pass'——SKILL.md 也未把克隆列为核心能力，无夸大。
[ok] 元数据（license/stars/commit） — 仓库级 MIT、stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。

6Verdict & Scenarios

Turns breaking changes in 2.5 (voice_label → instruction) and stricter censorship into a complete migration guide with script-level error translation, significantly cutting migration overhead for existing users.

Emotion/prosody control closely mirrors real voice acting workflows: global instruction combined with intra-sentence () bracket instructions, complete with verified benchmark results from 2026-04-23.

Batch processing is resilient to single-line failures: censorship fallbacks and hybrid-model fallback strategies are designed as normal execution paths rather than exceptions.

The non-destructive A/B invariant protects production assets, paired with ab_compare to generate ready-to-paste comparison tables.

Transparently documents constraints: price volatility, unverified voice cloning, duration inflation, and known censorship issues are fully detailed in references without misrepresenting numbers to stakeholders.

Best for: Suitable for: Scenarios requiring Chinese/Japanese speech synthesis with emotion and intra-sentence prosody (game/app voice lines, dubbing); legacy projects migrating from step-tts-2 to stepaudio-2.5-tts (migration guide is primary); teams needing batch synthesis that can tolerate skipping single-line censorship blocks, or teams running dual-model A/B evaluations.

Not for: Not suitable for: Users without a StepFun Normal key; scenarios where content contains extensive censored terms that cannot be rewritten or mixed with legacy models (the entire batch will be blocked); users requiring voice cloning (unverified in this skill); texts over 1000 characters intended for a single generation (semantic splitting is mandatory); lightweight scenarios needing only neutral narration without emotional control (cheaper step-tts-2 variants suffice).

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload stepfun-tts.tar.gz

sha256: f7fa276a8ae68d1a…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.