lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

MKT AI Video — Extraer SRT + Segmentos de MP3

Transcribe un MP3 de locución en dos archivos utilizados en todo el pipeline de producción de videos cortos:

1. <stem>.srt — subtítulos SRT estándar (marcas de tiempo a nivel de segmento, usados para subtítulos)
2. <stem>_segments.json — marcas de tiempo a nivel de palabra (usados para colocación precisa de efectos de sonido, animación de subtítulos palabra por palabra y clasificación de segmentos posteriores)

Ambos archivos se escriben junto al MP3 por defecto. Los nombres de archivo siguen el nombre base del MP3, por ejemplo, voiceover.mp3 → voiceover.srt + voiceover_segments.json.

Cuándo usar esta habilidad

• El usuario te entrega un MP3 de locución y solicita SRT/transcripción/segmentos
• Una habilidad posterior (plan-short-video-edit, heygen-remotion-short-video-editor, renderizado de subtítulos) necesita marcas de tiempo a nivel de palabra y no existen aún
• Necesitas regenerar segmentos para una locución existente (por ejemplo, después de una regrabación)

Si ambos archivos de salida ya existen y son más recientes que el MP3, es preferible reutilizarlos en lugar de volver a ejecutar Whisper.

Entrada

Argumento	Obligatorio	Por defecto	Notas
mp3_path	sí	—	Ruta absoluta al archivo MP3
language	no	vi	Código de idioma de Whisper. Usa vi para locuciones en vietnamita, en para inglés
model	no	base	Tamaño del modelo Whisper: tiny / base / small / medium / large. base es un buen equilibrio para vietnamita; small ofrece una precisión notablemente mejor en vietnamita a aproximadamente el doble de costo
output_dir	no	Carpeta contenedora del MP3	Dónde escribir el SRT + JSON

Paso 1 — Ejecutar el script de transcripción

Reutiliza el script Whisper existente de la habilidad heygen-short-video — ya implementa exactamente este comportamiento, por lo que no duplicamos código:

uv run .claude/skills/heygen-short-video/scripts/transcribe_mp3.py "<mp3_path>" --language vi --model base

Esto produce:

• <mp3_parent>/<stem>.srt
• <mp3_parent>/<stem>_segments.json

Para escribir las salidas en otro lugar, añade --output-dir <path>.

Ejemplo — para workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.mp3:

uv run .claude/skills/heygen-short-video/scripts/transcribe_mp3.py \
  "workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.mp3" \
  --language vi --model base

Salidas:

• workspace/content/2026-04-09/video-short/learn-claude-code/voiceover.srt
• workspace/content/2026-04-09/video-short/learn-claude-code/voiceover_segments.json

Paso 2 — Verificación de cordura de la salida

Después de que el script termine, confirma que ambos archivos existen y tienen contenido no trivial:

ls -lh "<output_dir>/<stem>.srt" "<output_dir>/<stem>_segments.json"
head -20 "<output_dir>/<stem>.srt"

Esperado:

• El SRT comienza con 1\n00:00:00,000 --> 00:00:0X,XXX\n<texto>\n\n
• El JSON es un arreglo de objetos, cada uno con id, start, end, text, y un arreglo words de {word, start, end}

Si alguno de los archivos falta o está vacío, la ejecución falló: vuelve a leer el stderr del Paso 1 y muestra el error al usuario en lugar de continuar silenciosamente.

Referencia del formato de salida

voiceover.srt

1
00:00:00,000 --> 00:00:05,139
Đây là tài liệu học Claude Code tốt nhất mình từng thấy…

2
00:00:05,139 --> 00:00:07,299
Nếu bạn mới bắt đầu tìm hiểu Claude Code,

voiceover_segments.json

[
  {
    "id": 0,
    "start": 0.0,
    "end": 5.14,
    "text": "Đây là tài liệu học Claude Code tốt nhất…",
    "words": [
      { "word": "Đây", "start": 0.0, "end": 0.34 },
      { "word": "là",  "start": 0.94, "end": 1.12 }
    ]
  }
]

Las marcas de tiempo a nivel de palabra son lo que hace valioso a este JSON: las habilidades posteriores las usan para animación de subtítulos palabra por palabra, señales de efectos de sonido por palabra y detección precisa de límites de segmento. No elimines el arreglo words al realizar postprocesamiento.

Paso 3 — Corrección de texto basada en guion (REQUERIDO cuando el guion está disponible)

Whisper a menudo distorsiona el vietnamita mezclado con términos técnicos en inglés (por ejemplo, "Claude Code" → "Clocot", "MCP Servers" → "MCP Service", "prompt" → "PromGtt"). Siempre realiza esta corrección cuando el guion original está disponible (casi siempre lo está en el pipeline de video). Corrige el texto del SRT/JSON mientras conservas todas las marcas de tiempo:

1. Lee el SRT + JSON generados (mantén cada start/end sin cambios).
2. Alinea cada entrada del SRT con el fragmento correspondiente del guion original por posición.
3. Reemplaza el texto de Whisper con el texto del guion para ese fragmento.
4. Refleja la misma corrección en voiceover_segments.json en el campo text a nivel de segmento. Las entradas a nivel de palabra pueden permanecer tal como las produjo Whisper a menos que tengas una alineación de palabras confiable; está bien dejar words[].word como está porque las habilidades posteriores usan principalmente las temporalizaciones de palabras, no las cadenas de palabras.
5. Escribe ambos archivos de nuevo en su lugar.

Por qué: El texto del SRT se usa para subtítulos renderizados. Texto incorrecto = subtítulos incorrectos. Las marcas de tiempo de Whisper son confiables; el texto no lo es.

Omite este paso SOLO si el usuario no proporcionó explícitamente un guion. En el pipeline completo de video (mkt-full-ai-video), el guion siempre está disponible, por lo que esta corrección siempre se realiza.

Consejos y advertencias

• Elección del modelo: base maneja la mayoría de las locuciones claras bien. Para grabaciones ruidosas o acento fuerte, salta a small o medium. Los costos aumentan rápidamente más allá de small y rara vez se recuperan para contenido de formato corto.
• Idioma: Siempre pasa --language vi explícitamente para vietnamita. La detección automática ocasionalmente recurre a otros idiomas en clips cortos.
• Re-ejecuciones: Whisper es determinista para el mismo modelo + audio, por lo que volver a ejecutar solo ayuda si cambias el modelo o corriges el audio. No vuelvas a ejecutar esperando mejores resultados con el mismo tamaño de modelo.
• Comillas en rutas: Siempre pon entre comillas la ruta del MP3 — las carpetas de workspace a menudo contienen guiones, fechas y barras que romperán la expansión del shell sin comillas.
• Sin duplicación: Esta habilidad deliberadamente no incluye su propio script. Si te encuentras a punto de escribir un nuevo script de transcripción, detente — usa heygen-short-video/scripts/transcribe_mp3.py. Si ese script necesita cambios, edítalo allí para que todos los consumidores se beneficien.

Entrega

Después de que ambos archivos se hayan guardado y verificado, informa con:

SRT:      <ruta_absoluta>.srt
Segmentos: <ruta_absoluta>_segments.json
Número de segmentos: N
Duración total: X.Xs

Luego deja que el usuario (o la habilidad que llama) decida el siguiente paso — típicamente plan-short-video-edit para la planificación de producción, o consumo directo por heygen-remotion-short-video-editor.