lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

MKT AI Video — Extraire SRT + Segments depuis un MP3

Transcrivez un fichier MP3 de voix off en deux fichiers utilisés tout au long de la pipeline de production de vidéos courtes :

1. <stem>.srt — sous-titres SRT standards (timestamps au niveau du segment, utilisés pour les légendes)
2. <stem>_segments.json — timestamps au niveau du mot (utilisés pour un placement précis des effets sonores, une animation de légende mot par mot et une classification des segments en aval)

Les deux fichiers sont écrits à côté du MP3 par défaut. Les noms de fichiers suivent le nom de base du MP3 — par exemple voiceover.mp3 → voiceover.srt + voiceover_segments.json.

Quand utiliser cette compétence

• L'utilisateur vous remet un MP3 de voix off et demande un SRT / une transcription / des segments
• Une compétence en aval (plan-short-video-edit, heygen-remotion-short-video-editor, rendu de légendes) a besoin de timestamps au niveau du mot et ils n'existent pas encore
• Vous devez régénérer des segments pour une voix off existante (par exemple après un ré-enregistrement)

Si les deux fichiers de sortie existent déjà et sont plus récents que le MP3, privilégiez leur réutilisation plutôt que de relancer Whisper.

Entrée

Arg	Requis	Défaut	Notes
mp3_path	oui	—	Chemin absolu vers le fichier MP3
language	non	vi	Code langue Whisper. Utilisez vi pour les voix off en vietnamien, en pour l'anglais
model	non	base	Taille du modèle Whisper : tiny / base / small / medium / large. base offre un bon équilibre pour le vietnamien ; small donne une précision nettement meilleure en vietnamien pour environ 2× le coût
output_dir	non	Dossier parent du MP3	Où écrire le SRT + JSON

Étape 1 — Exécuter le script de transcription

Réutilisez le script Whisper existant de la compétence heygen-short-video — il implémente déjà exactement ce comportement, donc nous ne dupliquons pas le code :

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

Ceci produit :

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

Pour écrire les sorties ailleurs, ajoutez --output-dir <path>.

Exemple — pour 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

Sorties :

• 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

Étape 2 — Vérifier la cohérence de la sortie

Une fois le script terminé, confirmez que les deux fichiers existent et ont un contenu non trivial :

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

Attendu :

• Le SRT commence par 1\n00:00:00,000 --> 00:00:0X,XXX\n<texte>\n\n
• Le JSON est un tableau d'objets, chacun avec id, start, end, text et un tableau words de {word, start, end}

Si l'un des fichiers est manquant ou vide, l'exécution a échoué — relisez la sortie d'erreur de l'étape 1 et signalez l'erreur à l'utilisateur plutôt que de continuer silencieusement.

Référence du format de sortie

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

Les timestamps au niveau du mot sont ce qui rend ce JSON précieux — les compétences en aval les utilisent pour l'animation de légendes mot par mot, les indices d'effets sonores par mot et la détection précise des limites de segments. Ne supprimez pas le tableau words lors du post-traitement.

Étape 3 — Correction textuelle basée sur le script (OBLIGATOIRE lorsque le script est disponible)

Whisper déforme souvent le vietnamien mélangé à des termes techniques anglais (par exemple "Claude Code" → "Clocot", "MCP Servers" → "MCP Service", "prompt" → "PromGtt"). Effectuez toujours cette correction lorsque le script original est disponible (il l'est presque toujours dans la pipeline vidéo). Corrigez le texte du SRT/JSON tout en préservant tous les timestamps :

1. Lisez le SRT et le JSON générés (conservez chaque start/end inchangé).
2. Alignez chaque entrée SRT avec le bloc correspondant du script original par position.
3. Remplacez le texte de Whisper par le texte du script pour ce bloc.
4. Répercutez la même correction dans voiceover_segments.json au niveau du champ text du segment. Les entrées au niveau du mot peuvent rester telles que Whisper les a produites, sauf si vous disposez d'un alignement fiable des mots — il est acceptable de laisser words[].word tel quel car les compétences en aval utilisent principalement les timings des mots, pas les chaînes de caractères des mots.
5. Écrivez les deux fichiers à leur emplacement.

Pourquoi : Le texte SRT est utilisé pour les légendes rendues. Un texte erroné = des légendes erronées. Les timestamps de Whisper sont fiables ; le texte ne l'est pas.

Ignorer cette étape UNIQUEMENT si l'utilisateur n'a explicitement pas fourni de script. Dans la pipeline vidéo complète (mkt-full-ai-video), le script est toujours disponible — donc cette correction est toujours effectuée.

Conseils et pièges

• Choix du modèle : base gère la plupart des voix off claires. Pour les enregistrements bruyants ou un accent prononcé, passez à small ou medium. Les coûts augmentent rapidement au-delà de small et rapportent rarement pour du contenu court.
• Langue : Passez toujours --language vi explicitement pour le vietnamien. La détection automatique retombe parfois sur d'autres langues pour les clips courts.
• Ré-exécutions : Whisper est déterministe pour le même modèle + audio, donc relancer n'aide que si vous changez le modèle ou corrigez l'audio. Ne relancez pas en espérant de meilleurs résultats avec la même taille de modèle.
• Citation des chemins : Mettez toujours le chemin MP3 entre guillemets — les dossiers de l'espace de travail contiennent souvent des traits d'union, des dates et des barres obliques qui cassent l'expansion shell non citée.
• Pas de duplication : Cette compétence n'embarque délibérément pas son propre script. Si vous êtes sur le point d'écrire un nouveau script de transcription, arrêtez-vous — utilisez heygen-short-video/scripts/transcribe_mp3.py. Si ce script doit être modifié, éditez-le là-bas pour que tous les consommateurs en bénéficient.

Remise

Après que les deux fichiers sont sauvegardés et vérifiés, faites un rapport avec :

SRT :      <chemin absolu>.srt
Segments : <chemin absolu>_segments.json
Nombre de segments : N
Durée totale : X.Xs

Puis laissez l'utilisateur (ou la compétence appelante) décider de la prochaine étape — typiquement plan-short-video-edit pour la planification de production, ou une consommation directe par heygen-remotion-short-video-editor.