lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

MKT AI Vídeo — Extrair SRT + Segmentos de MP3

Transcreva um voiceover em MP3 para dois arquivos usados em todo o pipeline de produção de vídeos curtos:

1. <stem>.srt — legendas SRT padrão (timestamps em nível de segmento, usadas para legendas)
2. <stem>_segments.json — timestamps em nível de palavra (usados para posicionamento preciso de efeitos sonoros, animação de legendas palavra por palavra e classificação de segmentos downstream)

Ambos os arquivos são gravados ao lado do MP3 por padrão. Os nomes dos arquivos seguem a base do MP3 — por exemplo, voiceover.mp3 → voiceover.srt + voiceover_segments.json.

Quando usar este skill

• O usuário fornece um MP3 de voiceover e pede SRT / transcrição / segmentos
• Um skill downstream (plan-short-video-edit, heygen-remotion-short-video-editor, renderização de legendas) precisa de timestamps em nível de palavra e eles ainda não existem
• Você precisa regenerar segmentos para um voiceover existente (por exemplo, após regravação)

Se ambos os arquivos de saída já existirem e forem mais recentes que o MP3, prefira reutilizá-los em vez de executar o Whisper novamente.

Entrada

Arg	Obrigatório	Padrão	Notas
mp3_path	sim	—	Caminho absoluto para o arquivo MP3
language	não	vi	Código de idioma do Whisper. Use vi para voiceovers em vietnamita, en para inglês
model	não	base	Tamanho do modelo Whisper: tiny / base / small / medium / large. base é um bom equilíbrio para vietnamita; small oferece precisão notavelmente melhor para vietnamita a cerca de 2x o custo
output_dir	não	Pasta pai do MP3	Onde escrever o SRT + JSON

Passo 1 — Executar o script de transcrição

Reutilize o script Whisper existente do skill heygen-short-video — ele já implementa exatamente este comportamento, então não duplicamos código:

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

Isso produz:

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

Para gravar as saídas em outro lugar, adicione --output-dir <path>.

Exemplo — 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

Saídas:

• 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

Passo 2 — Verificação de sanidade da saída

Após o script terminar, confirme que ambos os arquivos existem e têm conteúdo não trivial:

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

Esperado:

• O SRT começa com 1\n00:00:00,000 --> 00:00:0X,XXX\n<texto>\n\n
• O JSON é um array de objetos, cada um com id, start, end, text e um array words de {word, start, end}

Se algum arquivo estiver faltando ou vazio, a execução falhou — releia o stderr do Passo 1 e mostre o erro ao usuário em vez de continuar silenciosamente.

Formato de saída de referência

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 }
    ]
  }
]

Os timestamps em nível de palavra são o que torna este JSON valioso — skills downstream os usam para animação de legendas palavra por palavra, dicas de SFX por palavra e detecção precisa de limites de segmento. Não remova o array words ao pós-processar.

Passo 3 — Correção de texto baseada em script (OBRIGATÓRIA quando o script estiver disponível)

O Whisper frequentemente distorce vietnamita misturado com termos técnicos em inglês (por exemplo, "Claude Code" → "Clocot", "MCP Servers" → "MCP Service", "prompt" → "PromGtt"). Sempre realize esta correção quando o script original estiver disponível (quase sempre está no pipeline de vídeo). Corrija o texto do SRT/JSON preservando todos os timestamps:

1. Leia o SRT + JSON gerados (mantenha todos os start/end inalterados).
2. Alinhe cada entrada SRT com o trecho correspondente do script original por posição.
3. Substitua o texto do Whisper pelo texto do script para aquele trecho.
4. Espelhe a mesma correção no voiceover_segments.json no campo text em nível de segmento. As entradas em nível de palavra podem permanecer como o Whisper as produziu, a menos que você tenha um alinhamento de palavras confiável — não há problema em deixar words[].word como está, pois os skills downstream usam principalmente os tempos das palavras, não as strings das palavras.
5. Grave ambos os arquivos de volta no lugar.

Por que: O texto do SRT é usado para legendas renderizadas. Texto errado = legendas erradas. Os timestamps do Whisper são confiáveis; o texto não é.

Pule esta etapa APENAS se o usuário explicitamente não forneceu um script. No pipeline de vídeo completo (mkt-full-ai-video), o script está sempre disponível — portanto, esta correção é sempre realizada.

Dicas e armadilhas

• Escolha do modelo: base lida bem com a maioria dos voiceovers limpos. Para gravações ruidosas ou sotaque forte, mude para small ou medium. Os custos aumentam rapidamente além de small e raramente compensam para conteúdo de formato curto.
• Idioma: Sempre passe --language vi explicitamente para vietnamita. A detecção automática ocasionalmente recorre a outros idiomas em clipes curtos.
• Reexecuções: O Whisper é determinístico para o mesmo modelo + áudio, então reexecutar só ajuda se você mudar o modelo ou corrigir o áudio. Não reexecute esperando melhores resultados no mesmo tamanho de modelo.
• Aspas no caminho: Sempre coloque o caminho do MP3 entre aspas — as pastas do workspace frequentemente contêm hífens, datas e barras que quebrarão a expansão do shell sem aspas.
• Sem duplicação: Este skill deliberadamente não inclui seu próprio script. Se você estiver prestes a escrever um novo script de transcrição, pare — use heygen-short-video/scripts/transcribe_mp3.py. Se esse script precisar de alterações, edite-o lá para que todos os consumidores se beneficiem.

Entrega

Após ambos os arquivos serem salvos e verificados, reporte com:

SRT:      <caminho absoluto>.srt
Segments: <caminho absoluto>_segments.json
Contagem de segmentos: N
Duração total: X.Xs

Em seguida, deixe o usuário (ou o skill chamador) decidir o próximo passo — normalmente plan-short-video-edit para planejamento de produção, ou consumo direto por heygen-remotion-short-video-editor.