lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

MKT AI Video — SRT und Segmente aus MP3 extrahieren

Transkribiere ein Voiceover-MP3 in zwei Dateien, die in der gesamten Kurzvideo-Produktionspipeline verwendet werden:

1. <stamm>.srt — Standard-SRT-Untertitel (segmentgenaue Zeitstempel, für Untertitel verwendet)
2. <stamm>_segments.json — Wortgenaue Zeitstempel (verwendet für präzise Soundeffekt-Platzierung, wortweise Caption-Animation und nachgelagerte Segmentklassifizierung)

Beide Dateien werden standardmäßig neben dem MP3 geschrieben. Die Dateinamen folgen dem MP3-Stamm — z. B. voiceover.mp3 → voiceover.srt + voiceover_segments.json.

Wann dieses Skill verwendet werden soll

• Der Benutzer übergibt Ihnen ein MP3-Voiceover und bittet um SRT / Transkript / Segmente
• Ein nachgelagertes Skill (plan-short-video-edit, heygen-remotion-short-video-editor, Caption-Rendering) benötigt Wort-Zeitstempel und diese existieren noch nicht
• Sie müssen Segmente für ein vorhandenes Voiceover neu generieren (z. B. nach einer Neuaufnahme)

Falls beide Ausgabedateien bereits existieren und neuer als das MP3 sind, bevorzugen Sie die Wiederverwendung anstelle einer erneuten Whisper-Ausführung.

Eingabe

Arg	Erforderlich	Standard	Hinweise
mp3_path	ja	—	Absoluter Pfad zur MP3-Datei
language	nein	vi	Whisper-Sprachcode. Verwenden Sie vi für vietnamesische Voiceovers, en für Englisch
model	nein	base	Whisper-Modellgröße: tiny / base / small / medium / large. base ist ein guter Kompromiss für Vietnamesisch; small liefert merklich bessere vietnamesische Genauigkeit bei etwa doppelten Kosten
output_dir	nein	Übergeordneter Ordner des MP3	Wo SRT + JSON geschrieben werden sollen

Schritt 1 — Das Transkriptionsskript ausführen

Verwenden Sie das vorhandene Whisper-Skript aus dem heygen-short-video-Skill — es implementiert bereits genau dieses Verhalten, sodass wir keinen Code duplizieren:

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

Dies erzeugt:

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

Um die Ausgaben woanders hin zu schreiben, hängen Sie --output-dir <pfad> an.

Beispiel — für 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

Ausgaben:

• 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

Schritt 2 — Ausgabe auf Plausibilität prüfen

Nachdem das Skript beendet ist, bestätigen Sie, dass beide Dateien existieren und nichttriviale Inhalte haben:

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

Erwartet:

• SRT beginnt mit 1\n00:00:00,000 --> 00:00:0X,XXX\n<text>\n\n
• JSON ist ein Array von Objekten, jeweils mit id, start, end, text und einem words-Array von {word, start, end}

Wenn eine der Dateien fehlt oder leer ist, ist der Lauf fehlgeschlagen — lesen Sie stderr aus Schritt 1 erneut und zeigen Sie dem Benutzer den Fehler an, anstatt stillschweigend fortzufahren.

Referenz des Ausgabeformats

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

Wortgenaue Zeitstempel machen diese JSON wertvoll — nachgelagerte Skills verwenden sie für wortweise Caption-Animation, wortgenaue Soundeffekt-Signale und präzise Segmentgrenzenerkennung. Entfernen Sie das words-Array bei der Nachbearbeitung nicht.

Schritt 3 — Skriptbasierte Textkorrektur (ERFORDERLICH, wenn das Skript verfügbar ist)

Whisper verunstaltet oft Vietnamesisch, das mit englischen Fachbegriffen gemischt ist (z. B. "Claude Code" → "Clocot", "MCP Servers" → "MCP Service", "prompt" → "PromGtt"). Führen Sie diese Korrektur immer durch, wenn das Originalskript verfügbar ist (was in der Videopipeline fast immer der Fall ist). Korrigieren Sie den SRT-/JSON-Text, während Sie alle Zeitstempel beibehalten:

1. Lesen Sie die generierte SRT + JSON (behalten Sie jeden start/end unverändert).
2. Gleichen Sie jeden SRT-Eintrag mit dem passenden Abschnitt des Originalskripts anhand der Position ab.
3. Ersetzen Sie den Whisper-Text durch den Skripttext für diesen Abschnitt.
4. Spiegeln Sie dieselbe Korrektur in voiceover_segments.json im Segment-text-Feld wider. Wortgenaue Einträge können so bleiben, wie Whisper sie erzeugt hat, es sei denn, Sie haben eine zuverlässige Wortausrichtung — es ist in Ordnung, words[].word unverändert zu lassen, da nachgelagerte Skills hauptsächlich die Wortzeitsteuerung und nicht die Wortstrings verwenden.
5. Schreiben Sie beide Dateien zurück an Ort und Stelle.

Warum: SRT-Text wird für gerenderte Untertitel verwendet. Falscher Text = falsche Untertitel. Zeitstempel von Whisper sind vertrauenswürdig; Text ist es nicht.

Überspringen Sie diesen Schritt NUR, wenn der Benutzer explizit kein Skript bereitgestellt hat. In der vollständigen Videopipeline (mkt-full-ai-video) ist das Skript immer verfügbar — daher wird diese Korrektur immer durchgeführt.

Tipps und Fallstricke

• Modellwahl: base bewältigt die meisten sauberen Voiceovers problemlos. Bei verrauschten Aufnahmen oder starkem Akzent wechseln Sie zu small oder medium. Die Kosten steigen jenseits von small schnell und zahlen sich selten für Kurzformatinhalte aus.
• Sprache: Übergeben Sie für Vietnamesisch immer explizit --language vi. Die automatische Erkennung fällt bei kurzen Clips gelegentlich auf andere Sprachen zurück.
• Neustarts: Whisper ist für dasselbe Modell + dieselbe Audio deterministisch, daher hilft ein erneuter Lauf nur, wenn Sie das Modell ändern oder die Audio korrigieren. Führen Sie keinen Neustart in der Hoffnung auf bessere Ergebnisse bei derselben Modellgröße durch.
• Pfad in Anführungszeichen: Setzen Sie den MP3-Pfad immer in Anführungszeichen — Arbeitsbereichsordner enthalten oft Bindestriche, Daten und Schrägstriche, die eine nicht quotierte Shell-Expansion zerstören.
• Keine Duplizierung: Dieses Skill enthält bewusst kein eigenes Skript. Wenn Sie sich dabei ertappen, ein neues Transkriptionsskript zu schreiben, hören Sie auf — verwenden Sie heygen-short-video/scripts/transcribe_mp3.py. Wenn dieses Skript geändert werden muss, bearbeiten Sie es dort, sodass alle Konsumenten davon profitieren.

Übergabe

Nachdem beide Dateien gespeichert und überprüft wurden, melden Sie zurück:

SRT:      <absoluter Pfad>.srt
Segments: <absoluter Pfad>_segments.json
Anzahl der Segmente: N
Gesamtdauer: X.Xs

Überlassen Sie dann dem Benutzer (oder dem aufrufenden Skill) die Entscheidung über den nächsten Schritt — typischerweise plan-short-video-edit für die Produktionsplanung oder die direkte Verwendung durch heygen-remotion-short-video-editor.