Communitygithub.com

daymade/claude-code-skills - StepFun Contextual TTS

Genera voz en chino/japonés con StepFun Contextual TTS, controlando emoción y prosodia mediante instrucciones en lenguaje natural en lugar de etiquetas fijas. Ideal para síntesis expresiva, lotes de voces y migración desde step-tts-2.

¿Qué es claude-code-skills - StepFun Contextual TTS?

Esta habilidad permite generar voz en chino y japonés utilizando el modelo Contextual TTS de StepFun, con control fino de emoción y prosodia a través de descripciones en lenguaje natural (parámetro `instruction`) y directivas inline entre paréntesis `()`. Soporta los modelos `stepaudio-2.5-tts` (predeterminado, con límite de 200 caracteres en instruction) y `stepaudio-3-tts` (hasta 500 caracteres, ideal para susurros y prosodia intensa). Es útil para síntesis emocional, generación por lotes de líneas de diálogo, migración desde step-tts-2 y voces clonadas (solo con 2.5/step-tts-2, no con v3). Incluye scripts para síntesis simple, por lotes y comparación A/B, y maneja errores comunes como `voice_label` no soportado en v3 y bloqueos por censura. No es para transcripción (usar stepfun-asr).

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

StepFun Contextual TTS (predeterminado stepaudio-2.5-tts)

Genera voz en chino/japonés con StepFun Contextual TTS: la emoción y la prosodia se controlan mediante descripciones en lenguaje natural, no etiquetas fijas. El modelo predeterminado es stepaudio-2.5-tts (el que usa el script incluido): en una comparación A/B ciega del 2026-09-16 con nuestros propios casos, 2.5 ganó los pares neutral / jiao / lively-girl 3:2. Elige stepaudio-3-tts cuando la línea sea un susurro o tenga prosodia intensa con () en línea — v3 ganó exactamente esos dos pares; v3 también eleva el límite de instruction a 500 caracteres (2.5 tiene 200). ⚠️ Nunca sintetices voces clonadas con v3 — v3 acepta el ID de voz clonada sin error pero retrocede silenciosamente a la voz femenina predeterminada. La causa raíz: toda la cadena de clonación de StepFun sigue en la familia 2.5 (la API de creación de clones solo acepta 2.5/step-tts-2/step-tts-mini, v3 no está en la lista; la síntesis de clones en v3 no se ha publicado). Los clones creados en ambas generaciones se pierden en v3: clon de step-tts-2 SIM 0.272, clon nuevo creado con 2.5 SIM 0.195 (ancla 0.773), el mismo ID en 2.5 obtiene 0.743/0.678.

Complemento: para transcripción con stepaudio-3-asr-max (el modelo hermano), usa la habilidad stepfun-asr: comparten clave API pero viven en endpoints diferentes con formatos de cuerpo distintos.

Por qué existe esta habilidad — dos problemas no obvios que cuestan horas si no los conoces:

  1. stepaudio-3-tts rechaza voice_label (la forma de step-tts-2) — verificado en v3 2026-09-16: HTTP 400 voice_label no es compatible con este modelo. La emoción/prosodia se maneja mediante instruction (descripción en lenguaje natural, ≤500 caracteres en v3 — 200 era el límite de 2.5) y paréntesis () en línea dentro del propio texto.
  2. El comportamiento de censura depende de la versión del modelo — la lista de desencadenantes de la era 2.5 (死 / 消失 / términos políticos sensibles → censorship_block) no se activó en v3 en una prueba de muestra única del 2026-09-16; trata la censura como presente pero verifica de nuevo por cada desencadenante antes de construir mapas de reescritura. Las opciones de la era 2.5 están en references/migration_from_v2.md.

Configuración y autenticación

La clave API reside en $STEPFUN_API_KEY (preferida) o ${CLAUDE_PLUGIN_DATA}/config.json (alternativa para persistencia entre sesiones). Todos los scripts incluidos intentan primero la variable de entorno y luego el archivo de configuración.

Configuración inicial (en una línea):

mkdir -p "${CLAUDE_PLUGIN_DATA}" && cat > "${CLAUDE_PLUGIN_DATA}/config.json" <<EOF
{"api_key": "<pegar clave aquí>"}
EOF

Si el usuario no ha establecido una clave, pídele que la pegue (no adivines / no uses un marcador de posición). Las claves API de StepFun están disponibles en https://platform.stepfun.com/ → API Keys. Usa una clave Normal, no una clave Plan (las claves Plan están restringidas a modelos de texto y fallan silenciosamente en los endpoints de audio).

Tareas comunes — árbol de decisión

El usuario quiere...ScriptDetalle clave
Sintetizar 1–500 caracteres en chino con emociónscripts/tts_generate.pyUsa instruction para el estado de ánimo, () para prosodia en línea
Sintetizar texto largo (500–1000 caracteres)scripts/tts_generate.py1000 caracteres es el límite máximo; dividir en límites semánticos por encima de eso
Generar por lotes líneas de voz para juegos/aplicacionesscripts/tts_generate.py --batch <jsonl>Manejar la alternativa censorship_block individualmente
Comparar A/B dos modelos TTSscripts/ab_compare.shCompara duración/tamaño entre dos directorios
Migrar desde step-tts-2 / stepaudio-2.5-ttsver references/migration_from_v2.mdvoice_label.emotion → reescritura instruction + lista de censura de la era 2.5

Puntos de inicio

  • Sintetizar una sola línea: Ejecuta python3 scripts/tts_generate.py --text "你好" --out /tmp/hello.mp3 --instruction "温暖的希望感". Para control detallado, lee la sección "Contextual TTS" a continuación.
  • Desde código: este script es el envoltorio del endpoint en llm-registry — llmreg.wrapper_for("stepfun-tts").tts_generate.synthesize(api_key=…, text=…, model=…, extra={…}). extra se fusiona en el cuerpo de la solicitud tal cual; con {"timestamp": True, "return_url": True} el servidor responde con un sobre JSON ({"data": {"url", "subtitles"}}) que vuelve bajo json en lugar de audio_bytes (verificado 2026-09-19). Los parámetros no se facturan — envía lo que necesites. Las llamadas directas a /v1/audio/speech desde otros lugares están bloqueadas por el hook llm-entry-guard.
  • Una migración completa de step-tts-2 a Contextual TTS: lee references/migration_from_v2.md de principio a fin antes de tocar el código. Contiene el INSTRUCTION_MAP, el patrón de lista SKIP_CENSORED y la estrategia de directorio de salida para A/B no destructivo (escrito para 2.5; los mecanismos de migración son idénticos en v3).

Contextual TTS — más allá de las etiquetas de emoción

La característica principal de stepaudio-3-tts es que dejas de mapear emociones a etiquetas fijas y empiezas a describir lo que quieres en lenguaje natural. Dos capas:

Contexto global (parámetro instruction) — establece el tono general de toda la expresión. ≤500 caracteres en v3 (2.5 tenía 200; una instrucción de 300 caracteres verificada como aceptada en v3 2026-09-16). Piensa en ello como dar dirección de escena a un actor de voz.

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

Contexto en línea (paréntesis () dentro de input) — directivas dentro de la oración. El contenido entre paréntesis se consume como direcciones y NO se lee en voz alta. Úsalo para control preciso de pausas, respiración, énfasis o cambios de emoción en medio de la frase.

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

Ejemplos que funcionaron en la práctica (verificado 2026-04-23 en 2.5; los cinco re-verificados en v3 2026-09-16, incluidos estos casos de instrucción y prosodia en línea):

  • instruction: "活泼俏皮,像是在撒娇,带点嘴硬" — acelera visiblemente la entrega respecto a neutral
  • instruction: "耳语声,气声很重,几乎听不清" — produce susurro/respiración audible
  • input: "你好(停顿一下)我是蕾格(轻声)今天(加重)的天气真不错。" — directivas en línea respetadas todas

Lo que stepaudio-3-tts NO aceptará — el parámetro voice_label. Error en v3: voice_label no es compatible con este modelo (2.5 decía ...para modelos v2). Esta es la principal trampa de migración desde step-tts-2.

Patrones de error comunes (errores reales, soluciones reales)

Respuesta de errorCausa realSolución
"voice_label no es compatible con este modelo" (v3) / "...para modelos v2" (2.5)Se envió voice_label a un modelo Contextual TTSElimina voice_label; pon la misma intención en instruction como lenguaje natural
"El contenido que proporcionaste o la máquina generó está bloqueado." tipo: censorship_blockPalabra sensible (era 2.5: 死 / 消失 / etc.; desencadenantes de v3 no verificados)Reescribe la frase O retrocede a step-tts-2 para esa línea específica (modelo mixto está bien)
Truncamiento de audio silencioso (input > 1000 caracteres)Límite máximo excedidoDivide en límites semánticos; no trunques en medio de una oración

Más en references/known_issues.md.

Cuándo leer las referencias

  • references/api_reference.md — JSON exacto de solicitud/respuesta para /v1/audio/speech, todos los campos, respuestas de error. Léelo al escribir llamadas HTTP directas en lugar de usar los scripts incluidos.
  • references/migration_from_v2.md — guía completa para mover un proyecto de step-tts-2 a Contextual TTS. Contiene la tabla de reescritura emoción→instruction, la estrategia de directorio A/B, los puntos de control de decisión y los datos de compensación velocidad/calidad de abril de 2026 (escritos contra 2.5). Léelo antes de cualquier trabajo de migración.
  • references/known_issues.md — patrones de censura, inflación de duración TTS, error de nomenclatura de parámetros de la familia v2, límite máximo de 1000 caracteres. Verificación de la era 2.5; re-verifica en v3 antes de confiar en una entrada específica. Léelo al depurar salidas anómalas o evaluar si adoptar.

Invariantes de diseño (no romper estos)

  1. Salida A/B no destructiva — al regenerar un corpus con un nuevo modelo, escribe en un directorio paralelo (voice/zh_v3/), nunca sobrescribas el corpus de producción. La guía de migración muestra por qué.
  2. Manejo de censura por línea — si 2/29 líneas obtienen censorship_block, no falles el lote. Registra los IDs omitidos, continúa. La alternativa de modelo mixto (step-tts-2 para las 2 omitidas) es normal.
  3. No dupliques la lógica de voice_label en código nuevo — cualquier código TTS nuevo que apunte a stepaudio-3-tts debe usar solo instruction + () en línea. No escribas una rama que emita condicionalmente voice_label.

Datos específicos de v3 (verificados 2026-09-16)

  • Voces oficiales: 60+ mediante GET /v1/audio/system_voices?model=stepaudio-3-tts — la lista de 2.5 se hereda completamente, más voces nuevas (por ejemplo, nombres en inglés Lisa/Alfie, shanghainés shanghaifemale/shanghaimale).
  • Voces clonadas (复刻): NO uses stepaudio-3-tts — causa raíz confirmada 2026-09-16: toda la pila de clonación de StepFun sigue siendo de la familia 2.5. La API de creación (POST /v1/audio/voices) solo acepta stepaudio-2.5-tts / step-tts-2 / step-tts-mini, y v3 /v1/audio/speech retrocede silenciosamente a una voz femenina predeterminada para CUALQUIER ID clonado — SIM 0.272 (clon de step-tts-2) y 0.195 (clon nuevo creado con 2.5) frente al ancla 0.773; los mismos IDs en 2.5 obtienen 0.743/0.678. Sintetiza clones con stepaudio-2.5-tts (mejor SIM) o step-tts-2.
  • Sin transmisión WebSocket para v3 (a partir de 2026-09-16): wss://api.stepfun.com/v1/realtime/audio?model=stepaudio-3-tts se rechaza en el handshake (404), mientras que 2.5 todavía transmite allí. ¿Necesitas marcas de tiempo de subtítulos a nivel de carácter en v3? Usa REST timestamp:true + return_url:true (los subtítulos llegan en el JSON de respuesta data.subtitles[], nivel de carácter en ms, eje absoluto acumulado) — el simple stream_format:"audio" no puede transportar subtítulos (servidor 400).

Precios (verificados 2026-09-16, volátiles)

  • stepaudio-3-tts síntesis: 2.5 元 / 10,000 caracteres (página oficial del modelo, 2026-09-16 — más barato que los ~5.8 de la era 2.5)
  • Clonación de voz zero-shot: 9.9 元 / timbre

Vuelve a verificar en https://platform.stepfun.com/docs/zh/guides/pricing/details antes de citar a las partes interesadas.

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.

Skills relacionados