Communitygithub.com

daymade/claude-code-skills

使用阶跃星辰的上下文 TTS 生成中文/日语语音 — 預設模型為 stepaudio-2.5-tts,針對耳語或括號內韻律可選 stepaudio-3-tts。支援自然語言情感描述、批次語音生成及復刻語音(僅限 2.5/step-tts-2,不支援 v3)。

claude-code-skills 是什麼?

此技能讓 AI 代理能透過階躍星辰的 Contextual TTS 模型生成高品質中/日語語音。它封裝了兩個主要模型:stepaudio-2.5-tts(預設模型,在一般情感與韻律表現上表現優異)與 stepaudio-3-tts(專為耳語及精確括號內韻律設計,instruction 字數上限提升至 500 字)。關鍵特色是使用自然語言描述情感與韻律,取代了 step-tts-2 中固定的 voice_label 標籤,讓開發者能更直觀地控制語音合成效果。技能支援單句合成、批次處理遊戲/應用語音台詞、A/B 模型比較,並提供完整的遷移指南(從 step-tts-2 或 2.5 移至 Contextual TTS)。注意事項包括:v3 模型不接受 voice_label 參數、不支援復刻語音(復刻請使用 2.5 或 step-tts-2)、以及需注意不同版本的審查敏感詞清單。此技能廣泛相容於支援 SKILL.md 的代理平台(如 Claude Code、Cursor 等),透過環境變數 $STEPFUN_API_KEY 或 config.json 設定認證。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/daymade/claude-code-skills/tree/HEAD/daymade-audio/stepfun-tts

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

StepFun Contextual TTS(預設 stepaudio-2.5-tts)

使用階躍星辰的 Contextual TTS 生成中文/日語語音 — 情感與韻律透過自然語言描述,而非固定標籤。預設模型為 stepaudio-2.5-tts(捆綁腳本使用的模型):在 2026-09-16 的內部盲測 A/B 比較中,2.5 在 neutral / jiao / lively-girl 三組中以 3:2 獲勝。當語句為耳語或帶有大量括號內韻律時,請選用 stepaudio-3-tts — v3 在該兩組中勝出;此外 v3 將 instruction 字數上限提升至 500 字(2.5 為 200)。⚠️ 切勿使用 v3 合成復刻語音 — v3 合成時接受復刻音色 ID 不報錯,但會靜默回退至預設女聲——根本原因 = 階躍復刻鏈路整體停留在 2.5 家族(復刻建立 API 僅接受 2.5/step-tts-2/step-tts-mini,v3 不在列;v3 合成側的復刻功能尚未發布)。兩代建立的克隆在 v3 上皆失效:step-tts-2 克隆相似度 0.272、2.5 建立的新克隆相似度 0.195(錨點 0.773),2.5 同 ID 則為 0.743/0.678。

夥伴:如需使用 stepaudio-3-asr-max(同系列模型)進行語音轉寫,請使用 stepfun-asr 技能 — 兩者共用 API Key,但使用不同端點與不同請求結構。

為何需要此技能 — 若不事先了解,有兩個不易察覺的陷阱可能浪費數小時:

  1. stepaudio-3-tts 拒絕 voice_label(step-tts-2 的方式)— 於 v3 2026-09-16 驗證:HTTP 400 voice_label is not supported for this model。情感/韻律透過 instruction(自然語言描述,v3 上限 500 字 — 2.5 為 200)及文字內的括號 () 控制。
  2. 審查行為依模型版本而異 — 2.5 時代的觸發清單(死/消失/敏感政治用語 → censorship_block)在 2026-09-16 的單一樣本測試中並未觸發 v3;請將審查視為存在,但在建立改寫對應表前,請針對每個觸發條件重新驗證。2.5 時代的選項詳見 references/migration_from_v2.md。

設定與認證

API Key 存放於 $STEPFUN_API_KEY(建議)或 ${CLAUDE_PLUGIN_DATA}/config.json(跨 session 持久化的備用方案)。所有捆綁腳本會優先讀取環境變數,再讀取設定檔。

首次設定(一行指令):

mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<貼上你的 Key>"}
EOF

若使用者尚未設定 Key,請要求他們貼上(請勿猜測或使用佔位符)。StepFun API Key 可在 https://platform.stepfun.com/ → API Keys 取得。請使用 Normal Key,不要使用 Plan Key(Plan Key 僅限文字模型,在音訊端點上會靜默失敗)。

常見任務 — 決策樹

使用者需求...腳本關鍵細節
合成 1–500 字中文語音(含情感)scripts/tts_generate.py使用 instruction 設定情緒,() 控制行內韻律
合成長文字(500–1000 字)scripts/tts_generate.py1000 字為硬性上限;超過時請依語意邊界分割
批次生成遊戲/應用語音台詞scripts/tts_generate.py --batch <jsonl>逐行處理 censorship_block 的備援邏輯
A/B 比較兩種 TTS 模型scripts/ab_compare.sh比較兩個目錄下的合成時長與檔案大小
從 step-tts-2 / stepaudio-2.5-tts 遷移詳見 references/migration_from_v2.mdvoice_label.emotion → instruction 改寫 + 2.5 時代審查清單

起點

  • 合成單一句子:執行 python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "溫暖的希望感"。如需更細緻的控制,請閱讀下方「Contextual TTS」段落。
  • 從程式碼呼叫:此腳本為 llm-registry 中端點的包裝 — llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…})。extra 將原樣合入請求主體;搭配 {"timestamp": True, "return_url": True} 時,伺服器會回傳 JSON 封包({"data": {"url", "subtitles"}}),並以 json 而非 audio_bytes 形式回傳(2026-09-19 驗證)。參數不計費 — 放心發送所需內容。其他地方直接呼叫 /v1/audio/speech 會被 llm-entry-guard 鉤子攔截。
  • 完整遷移從 step-tts-2 → Contextual TTS:在動任何程式碼前,請完整閱讀 references/migration_from_v2.md。該文件包含 INSTRUCTION_MAP、SKIP_CENSORED 清單模式,以及非破壞性 A/B 比較的輸出目錄策略(以 2.5 為基礎撰寫;遷移機制在 v3 上完全相同)。

Contextual TTS — 超越情感標籤

stepaudio-3-tts 的主要功能是:你不再將情感對應到固定標籤,而是開始用自然語言描述你的需求。共有兩層:

全域上下文(instruction 參數) — 設定整個語句的整體語氣。v3 上限 500 字(2.5 為 200;300 字的 instruction 已於 2026-09-16 在 v3 上驗證可正常使用)。可以想像成你在對配音演員下達舞台指示。

instruction: "剋制的悲傷,語氣低沉柔弱,像快要消失一樣"

行內上下文(input 中的 () 括號) — 句內的指令。括號內的內容會被視為指示,不會被朗讀出來。可用於精確控制停頓、氣息、強調或句中的情緒轉變。

input: "(試探著問)你好嗎?(開心地)太好了!(突然沉下來)不過...我快要消失了。"

實際驗證可行的範例(2026-04-23 於 2.5 驗證;全部五個範例於 2026-09-16 在 v3 上重新驗證,包含這些 instruction 和行內韻律案例):

  • instruction: "活潑俏皮,像是在撒嬌,帶點嘴硬" — 明顯比中性語氣加快語速
  • instruction: "耳語聲,氣聲很重,幾乎聽不清" — 產生可聽到的耳語/氣聲
  • input: "你好(停頓一下)我是蕾格(輕聲)今天(加重)的天氣真不錯。" — 行內指令全部生效

stepaudio-3-tts 不會接受的參數 — voice_label 參數。v3 錯誤訊息:voice_label is not supported for this model(2.5 回傳 ...for v2 models)。這是從 step-tts-2 遷移時的第一大陷阱。

常見錯誤模式(真實錯誤,真實解法)

錯誤回應實際原因解法
"voice_label is not supported for this model"(v3)/ "...for v2 models"(2.5)將 voice_label 傳給 Contextual TTS 模型移除 voice_label;將相同意圖改為自然語言的 instruction
"The content you provided or machine outputted is blocked." type: censorship_block敏感詞(2.5 時代:死/消失等;v3 觸發條件未驗證)改寫該詞句,或對該行改用 step-tts-2(混合模型可行)
音訊靜默截斷(輸入 > 1000 字)超出硬性上限依語意邊界分割;請勿在句中截斷

更多請見 references/known_issues.md。

何時閱讀參考文件

  • references/api_reference.md — /v1/audio/speech 的完整 request/response JSON、所有欄位、錯誤回應。當你直接撰寫原始 HTTP 呼叫而非使用捆綁腳本時閱讀。
  • references/migration_from_v2.md — 將 step-tts-2 專案遷移至 Contextual TTS 的完整操作手冊。內含情感→instruction 改寫對照表、A/B 目錄策略、決策檢查點,以及 2026-04 的速度/品質權衡資料(基於 2.5 撰寫)。請在進行任何遷移工作前閱讀。
  • references/known_issues.md — 審查模式、TTS 時長膨脹、v2 家族參數命名陷阱、1000 字硬性上限。基於 2.5 時代驗證;若需依賴特定項目,請在 v3 上重新驗證。除錯異常輸出或評估是否採用時閱讀。

設計不變原則(請勿違反)

  1. 非破壞性 A/B 輸出 — 使用新模型重新生成語料時,請寫入平行目錄(voice/zh_v3/),切勿覆蓋生產用語料。遷移手冊說明了原因。
  2. 逐行處理審查 — 若 29 行中有 2 行觸發 censorship_block,不應讓整個批次失敗。記錄跳過的 ID,繼續處理。混合模型備援(被跳過的 2 行改用 step-tts-2)是正常做法。
  3. 新程式碼中請勿重複 voice_label 邏輯 — 任何針對 stepaudio-3-tts 的新 TTS 程式碼,應僅使用 instruction + 行內 ()。請勿撰寫會條件式產生 voice_label 的分支。

v3 專屬事實(2026-09-16 驗證)

  • 官方語音:透過 GET /v1/audio/system_voices?model=stepaudio-3-tts 可取得 60+ 種 — 2.5 的清單完整繼承,並新增語音(例如英文名稱的 Lisa/Alfie、上海話 shanghaifemale/shanghaimale)。
  • 復刻語音:請勿使用 stepaudio-3-tts — 2026-09-16 鎖定根本原因:階躍的整個復刻堆疊仍屬於 2.5 家族。建立 API(POST /v1/audio/voices)僅接受 stepaudio-2.5-tts / step-tts-2 / step-tts-mini,而 v3 的 /v1/audio/speech 對任何復刻 ID 會靜默回退至預設女聲 — 相似度 0.272(step-tts-2 克隆)和 0.195(全新的 2.5 克隆)對比錨點 0.773;相同 ID 在 2.5 上得分為 0.743/0.678。請使用 stepaudio-2.5-tts(最佳相似度)或 step-tts-2 合成復刻語音。
  • v3 不支援 WebSocket 串流(截至 2026-09-16):wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-tts 在握手階段即被拒絕(404),而 2.5 仍可串流。需要在 v3 上取得逐字字幕時間戳?請使用 REST 的 timestamp:true + return_url:true(字幕會出現在回應 JSON 的 data.subtitles[] 中,包含逐字毫秒時間戳與累積絕對軸)— 單純的 stream_format:"audio" 無法承載字幕(伺服器回傳 400)。

價格(2026-09-16 驗證,可能變動)

  • stepaudio-3-tts 合成:2.5 元 / 萬字元(官方模型頁面,2026-09-16 — 比 2.5 時代的約 5.8 便宜)
  • 零樣本語音復刻:9.9 元 / 音色

在向利害關係人報價前,請至 https://platform.stepfun.com/docs/zh/guides/pricing/details 重新驗證。

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

daymade/claude-code-skills

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

daymade/claude-code-skills

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

daymade/local-conversation-history

Entry point for local AI conversation history across providers. Routes a request to the one skill that owns it, by platform (Claude Code, OpenAI Codex, Kimi CLI) and action (read evidence vs continue interrupted work), and owns the one job none of them own alone: a single inventory spanning all three providers. Use when the provider is unknown or plural ("our history", "what have I been working on", "which chats did I have"), when the user wants Kimi CLI history at all, when it is unclear whether they need evidence or resumption, or when they ask for this skill by name. Vague recall that names no platform ("we discussed this once, when was it?") belongs here rather than to a single-provider reader, because a Claude-only answer to an unscoped question cannot support an absence claim. When the platform and the action are both already clear, load that executor skill directly instead — except Kimi CLI, which has no reader or continuation skill of its own and always routes through here.

daymade/ppt-creator

Create professional slide decks from topics or documents. Generates structured content with data-driven charts, speaker notes, and complete PPTX files. Applies persuasive storytelling principles (Pyramid Principle, assertion-evidence). Supports multiple formats (Marp, PowerPoint). Use for presentations, pitches, slide decks, or keynotes.

daymade/prompt-optimizer

Transform vague prompts into precise, well-structured specifications using EARS (Easy Approach to Requirements Syntax) methodology. This skill should be used when users provide loose requirements, ambiguous feature descriptions, or need to enhance prompts for AI-generated code, products, or documents. Triggers include requests to "optimize my prompt", "improve this requirement", "make this more specific", or when raw requirements lack detail and structure.

daymade/qa-expert

This skill should be used when establishing comprehensive QA testing processes for any software project. Use when creating test strategies, writing test cases following Google Testing Standards, executing test plans, tracking bugs with P0-P4 classification, calculating quality metrics, or generating progress reports. Includes autonomous execution capability via master prompts and complete documentation templates for third-party QA team handoffs. Implements OWASP security testing and achieves 90% coverage targets.

daymade/read-claude-code-history

Reads, searches, and exports local Claude Code history without resuming work. Covers recent session inventory, exact session timelines, verbatim human input including queued mid-turn prompts, full-event keyword search, hybrid recall when wording changed, end-state triage, and deleted-file recovery across active Claude homes plus registered archives. Use whenever the user asks what they or Claude said, wants a Claude Code session ID or original context, remembers prior work vaguely, needs an old file from a transcript, or must prove what a Claude session contained before continuing it. Also owns the only Kimi CLI surface, via its Kimi inventory and search flags. For Codex history use read-codex-history; when the request names no platform at all or spans providers, start at local-conversation-history.

daymade/read-codex-history

Reads, searches, and exports local OpenAI Codex history without continuing the old task. Lists recent Codex sessions, extracts exact prompt-ledger inputs by Session, locates a rollout by verified session_meta identity, reconstructs one chronological user/assistant timeline with fork and compaction lineage, and performs bounded keyword search across live and archived rollouts. Use whenever the user asks what they told Codex, wants recent original inputs, a Codex Session ID, full prior context, fork ancestry, or evidence of what a Codex run did. For Claude Code history use read-claude-code-history.

daymade/twitter-reader

Fetch Twitter/X post content including long-form Articles with full images and metadata. Use when Claude needs to retrieve tweet/article content, author info, engagement metrics, and embedded media. Supports individual posts and X Articles (long-form content). Automatically downloads all images to local attachments folder and generates complete Markdown with proper image references. Preferred over Jina for X Articles with images.

相關技能