Communitygithub.com

StepFun 맥락 TTS (기본 stepaudio-2.5-tts)

StepFun의 맥락 TTS를 사용하여 중국어/일본어 음성을 생성합니다. 감정과 운율을 자연어 설명으로 제어하며, 고정된 레이블 대신 instruction을 사용합니다. step-tts-2에서 마이그레이션하는 경우, 클론 음성 합성, 감정/운율 제어 합성에 유용합니다.

StepFun 맥락 TTS (기본 stepaudio-2.5-tts)란 무엇인가요?

이 스킬은 Claude Code에서 StepFun의 맥락 TTS(문맥 인식 텍스트 음성 변환) 모델을 호출하여 중국어와 일본어 음성을 합성할 수 있게 해줍니다. 기본 모델은 `stepaudio-2.5-tts`이며, 더 긴 instruction(최대 500자)과 인라인 `()` 운율 지시가 필요할 때는 `stepaudio-3-tts`를 선택할 수 있습니다. 감정과 운율을 'voice_label' 대신 자연어 'instruction' 파라미터로 제어하는 것이 핵심이며, v3 모델에서 voice_label을 사용하면 HTTP 400 오류가 발생합니다. 또한, 게임/앱 대사 일괄 생성, A/B 비교, step-tts-2에서의 마이그레이션, 클론 음성 관리(2.5/step-tts-2에서만 가능, v3에서는 불가) 등 다양한 작업을 지원합니다. 검열 동작은 모델 버전에 따라 다르므로 주의해야 하며, API 키는 환경 변수나 설정 파일을 통해 구성합니다. 이 스킬은 음성 합성 전용이며, 음성 인식에는 사용할 수 없습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/daymade/claude-code-skills/tree/HEAD/daymade-audio/stepfun-tts

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

StepFun 맥락 TTS (기본 stepaudio-2.5-tts)은(는) 무엇을 하나요?

StepFun의 맥락 TTS로 중국어/일본어 음성을 생성합니다. 감정과 운율은 고정된 레이블이 아닌 자연어 설명을 통해 제어합니다. **기본 모델은 stepaudio-2.5-tts**입니다(번들 스크립트가 사용하는 모델). 2026-09-16 자체 사례에 대한 블라인드 A/B 테스트에서 2.5는 중립 / 娇 / lively-girl 쌍에서 3:2로 우세했습니다. 속삭임이나 무거운 인라인 () 운율이 필요한 경우 stepaudio-3-tts를 선택하세요 — v3는 해당 두 쌍에서 정확히 승리했습니다. 또한 v3는 instruction 한도를 500자로 올립니다(2.5는 200자). ⚠️ 클론 음성을 v3로 합성하지 마세요 — v3 음성은 복제 음색 ID를 수용하지만 오류 없이 자동으로 기본 여성 음성으로 대체됩니다. 근본 원인은 StepFun의 전체 복제 파이프라인이 2.5 제품군에 머물러 있기 때문입니다(복제 생성 API는 2.5/step-tts-2/step-tts-mini만 허용하며 v3는 목록에 없음). 두 세대에서 생성된 클론은 v3에서 모두 손실됩니다: step-tts-2 클론 SIM 0.272, 2.5에서 생성된 새 클론 SIM 0.195(앵커 0.773), 2.5에서 동일 ID는 0.743/0.678.

참고: stepaudio-3-asr-max(형제 모델)를 사용한 전사의 경우 stepfun-asr 스킬을 사용하세요. 두 모델은 API 키를 공유하지만 다른 엔드포인트와 다른 본문 형식을 사용합니다.

이 스킬이 존재하는 이유 — 알지 못하면 많은 시간을 낭비할 수 있는 두 가지 명확하지 않은 함정 때문입니다:

  1. stepaudio-3-tts는 voice_label을 거부합니다(step-tts-2 방식). 2026-09-16 v3에서 확인: HTTP 400 voice_label is not supported for this model. 감정/운율은 instruction(자연어 설명, v3에서 ≤500자 — 200자는 2.5 제한)과 텍스트 자체 내의 인라인 () 괄호를 통해 전달됩니다.
  2. 검열 동작은 모델 버전에 따라 다릅니다. 2.5 시대의 트리거 목록(死 / 消失 / 민감한 정치 용어 → censorship_block)은 2026-09-16 단일 샘플 프로브에서 v3에서 발생하지 않았습니다. 검열이 존재한다고 간주하되 재작성 맵을 구축하기 전에 트리거당 다시 확인하세요. 2.5 시대 옵션은 references/migration_from_v2.md에 있습니다.

구성 및 인증

API 키는 $STEPFUN_API_KEY(권장) 또는 ${CLAUDE_PLUGIN_DATA}/config.json(세션 간 지속성을 위한 대체)에 있습니다. 번들된 모든 스크립트는 먼저 환경 변수를 시도한 다음 구성을 시도합니다.

최초 설정(한 줄):

mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<키를 여기에 붙여넣기>"}
EOF

사용자가 키를 설정하지 않은 경우, 키를 붙여넣도록 요청하세요(추측하지 말고 자리 표시자를 사용하지 마세요). StepFun API 키는 https://platform.stepfun.com/ → API Keys에서 얻을 수 있습니다. Plan 키가 아닌 Normal 키를 사용하세요(Plan 키는 텍스트 모델로 제한되며 오디오 엔드포인트에서 자동으로 실패합니다).

일반적인 작업 — 결정 트리

사용자 원하는 것...스크립트주요 세부 사항
감정을 포함한 1–500자 중국어 합성scripts/tts_generate.py분위기에 instruction 사용, 인라인 운율에 () 사용
긴 텍스트(500–1000자) 합성scripts/tts_generate.py1000자는 하드 상한; 그 이상은 의미 경계에서 분할
게임/앱 대사 일괄 생성scripts/tts_generate.py --batch <jsonl>각각에 대해 censorship_block 대체를 개별적으로 처리
두 TTS 모델 A/B 비교scripts/ab_compare.sh두 디렉터리 간의 지속 시간/크기 비교
step-tts-2 / stepaudio-2.5-tts에서 마이그레이션references/migration_from_v2.md 참조voice_label.emotion → instruction 재작성 + 2.5 시대 검열 목록

시작점

  • 단일 라인 합성: python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "溫暖的希望感"을 실행하세요. 세부 제어는 아래 "맥락 TTS" 섹션을 읽으세요.
  • 코드에서: 이 스크립트는 llm-registry의 엔드포인트 래퍼입니다 — llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}). extra는 요청 본문에 그대로 병합됩니다. {"timestamp": True, "return_url": True}를 사용하면 서버가 {"data": {"url", "subtitles"}} 형식의 JSON 응답을 반환합니다(json 아래에 audio_bytes 대신, 2026-09-19 확인). 매개변수는 청구되지 않습니다. 필요한 것을 보내세요. 다른 곳에서 /v1/audio/speech를 직접 호출하면 llm-entry-guard 훅에 의해 차단됩니다.
  • step-tts-2에서 맥락 TTS로의 전체 마이그레이션: 코드를 만지기 전에 references/migration_from_v2.md를 끝까지 읽으세요. INSTRUCTION_MAP, SKIP_CENSORED 목록 패턴, 비파괴 A/B를 위한 출력 디렉터리 전략이 있습니다(2.5용으로 작성되었지만 마이그레이션 메커니즘은 v3에서 동일합니다).

맥락 TTS — 감정 레이블을 넘어서

stepaudio-3-tts의 핵심 기능은 감정을 고정된 태그에 매핑하는 것을 중단하고 원하는 것을 자연어로 설명하기 시작한다는 것입니다. 두 가지 계층:

전역 맥락(instruction 매개변수) — 전체 발화의 전반적인 분위기를 설정합니다. v3에서 ≤500자(2.5는 200자; 300자 instruction이 v3에서 수락됨 2026-09-16 확인). 성우에게 무대 지시를 내리는 것으로 생각하세요.

instruction: "克制的悲伤,语气低沉柔弱,像快要消失一样"

인라인 맥락(input 내의 () 괄호) — 문장 내 지시사항. 괄호 안의 내용은 지시사항으로 소비되며 소리내어 읽히지 않습니다. 일시 중지, 호흡, 강조 또는 문장 중간 감정 변화의 정밀한 제어에 사용합니다.

input: "(试探着问)你好吗?(开心地)太好了!(突然沉下来)不过...我快要消失了。"

실제로 작동한 예(2.5에서 2026-04-23 확인, 모든 5개는 v3에서 2026-09-16 재확인, 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)맥락 TTS 모델에 voice_label 전송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의 정확한 요청/응답 JSON, 모든 필드, 오류 응답. 번들 스크립트 대신 원시 HTTP 호출을 작성할 때 읽으세요.
  • references/migration_from_v2.md — step-tts-2 프로젝트를 맥락 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 확인)

  • 공식 음성: 60개 이상 (GET /v1/audio/system_voices?model=stepaudio-3-tts 통해) — 2.5 목록을 완전히 상속하며, 새 음성(예: 영어 이름 Lisa/Alfie, 상하이어 shanghaifemale/shanghaimale)이 추가됨.
  • 클론(复刻) 음성: stepaudio-3-tts를 사용하지 마세요 — 2026-09-16 근본 원인 확인: StepFun의 전체 클론 스택은 여전히 2.5 제품군입니다. 생성 API(POST /v1/audio/voices)는 stepaudio-2.5-tts / step-tts-2 / step-tts-mini만 허용하며 v3 /v1/audio/speech는 모든 클론 ID에 대해 자동으로 기본 여성 음성으로 대체됩니다 — SIM 0.272(step-tts-2 클론) 및 0.195(새 2.5 생성 클론) 대 앵커 0.773; 2.5의 동일 ID는 0.743/0.678입니다. 클론은 stepaudio-2.5-tts(최상의 SIM) 또는 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[]에 도착, 문자 수준 ms, 누적 절대 축) — 일반 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.

관련 스킬