chenlikun2010/product-promo-video-skill

Produkt-Promo-Video-Erstellung (Remotion)

Aus einem „Materialverzeichnis + kreativen Ideen“ ein direkt abspielbares MP4-Promo-Video erstellen. Der Hauptteil wird lokal mit Remotion (React-basierte, codierte Videos) gerendert – reproduzierbar und leicht anpassbar. Für Drehbuch, TTS und kleine Ergänzungsaufnahmen wird primär die Alibaba Cloud Bailian CLI bl verwendet.

Geeignet für: Motion-Graphics-Promo-Videos, die hauptsächlich aus Bildern/Produktfotos/Mini-App-Screenshots/Kurzvideos bestehen, mit Text + Animation + Voice-Over (z. B. für Messeschleifen, Produktvorstellungen, Konferenz-Opener). Nicht geeignet für: Aufnahmen mit viel Live-Action oder komplexen Kamerabewegungen. Fehlende Szenen können mit dem Bailian HappyHorse-Modell ergänzt und dann in Remotion zusammengeführt werden.

Voraussetzungen

• node (>=18), npm, ffmpeg/ffprobe, python3 (mit numpy, requests). Vor Beginn mit which node ffmpeg python3 prüfen.
• bl CLI installiert und angemeldet: bl --version, bl auth status. Vor der Nutzung von bl die Version gemäß den Preflight-Regeln des bailian-cli-Skills prüfen.
• Beim Rendern muss eine Internetverbindung bestehen (für den ersten Ladevorgang der Schriftart Noto Sans SC).

Standard-Workflow (in dieser Reihenfolge ausführen)

1. Material und Absichten erfassen

• Den Benutzer nach dem Materialverzeichnis und den kreativen Ideen/Verkaufsargumenten fragen. Zuerst das Verzeichnis auflisten: find <dir> -type f \( -iname '*.jpg' -o -iname '*.png' -o -iname '*.mp4' -o -iname '*.mov' \).
• Jedes Schlüsselbild einzeln lesen (Produkt, Funktionen, Oberfläche erkennen), bei jedem Video mit ffprobe Dauer/Codierung/Auflösung ermitteln.
• Fallstricke erkennen: ① Ungünstige Daten in Screenshots (z. B. „Medikamenteneinnahmequote 4%“) müssen im Video mit React durch positive Daten überdeckt werden; ② Bei mehrfarbigen/-modelligen Produkten die Hauptansicht auswählen; ③ Unrelevantes Material entfernen.

2. Storyboard entwerfen, zuerst mit dem Benutzer abstimmen (wichtig)

• Mit AskUserQuestion abstimmen: Stil, Dauer (für Messeschleifen 60–90 s empfohlen), Seitenverhältnis (Querformat 1920×1080 / Hochformat 1080×1920), Art der Sprachausgabe.
• Direkt aus 3 vorgefertigten Stilvorlagen wählen lassen (siehe styles/STYLES.md): warm (familiär-herzlich) / guochao (lebendig, chinesisch-modern) / tech (geschäftlich-technisch). Jede Vorlage enthält bereits Farbschemata, Dekorationen und Storyboards. Nach Auswahl direkt verwenden, kein Design von Grund auf nötig. Benötigt der Kunde einen neuen Stil, wird die ähnlichste Vorlage als Basis angepasst.
• Der Ton des Texts richtet sich nach dem Stil: emotionale Erzählung (warm/guochao) oder Unternehmens-/Produktvorstellung (tech).
• Zunächst mit Bailian einen Drehbuchentwurf / Storyboard erstellen, dann manuell verfeinern:

bl text chat \
  --system "Antworte in vereinfachtem Chinesisch. Gib eine kompakte Storyboard-Tabelle für das Produkt-Promo-Video aus." \
  --message "Erstelle basierend auf diesen Materialien und Verkaufsargumenten ein 60-Sekunden-Storyboard: <Materialliste + Verkaufsargumente>"

• Ergebnis: Storyboard-Tabelle: Jeder Abschnitt (Szene-Nr./Dauer/Bild/Große Texttafel/Voice-Over/Verwendetes Material). Grundsatz für Messeschleifen: Ohne Ton verständlich (hauptsächlich große Texttafeln), in 3 Sekunden fesseln, Ende kann nahtlos an Anfang anschließen.

3. Projekt aus der Vorlage erstellen

PROJ="$HOME/<Filmname>"
cp -R ~/.claude/skills/product-promo-video/template "$PROJ"
cd "$PROJ" && npm install
mkdir -p public/assets public/audio out

Die Vorlage enthält bereits: theme.ts (Farben/Schriftarten/SCENE_FRAMES), components.tsx (KenBurns/BigTitle/Subtitle/Narration/BgMusic/PhoneMock/Chip), Video.tsx (TransitionSeries mit Überblendung), Root.tsx, scenes/AllScenes.example.tsx (vollständiges Beispiel, nach Änderung als AllScenes.tsx speichern, damit Video darauf verweist).

4. Material in public/assets verarbeiten

• HEVC zwingend nach H.264 konvertieren (Chromium hat instabile HEVC-Dekodierung): ffmpeg -y -i in.mp4 -c:v libx264 -pix_fmt yuv420p -crf 20 -an public/assets/weather.mp4
• Bilder kopieren und in ASCII-Dateinamen umbenennen (staticFile ist instabil bei chinesischen Pfaden): intro.jpg / device.jpg / app_home.jpg ....
• Screenshots mit ungünstigen Daten wie gewohnt kopieren; die Überdeckung erfolgt in der Storyboard-Komponente durch React-Karten.

5. Optional: Bailian HappyHorse zur Szenenergänzung

• Wenn wichtige Szenen fehlen, können mit bl video generate / bl video ref Ergänzungsaufnahmen erstellt werden; bei ausreichendem Material kann dieser Schritt übersprungen und direkt mit Remotion-Effekten gearbeitet werden.
• Die Länge der HappyHorse-Videoproduktion im Skill nicht einschränken. --duration wird je nach Benutzeranforderung, Budget und Modellunterstützung eingestellt; bei längeren Filmen mehrere Clips generieren und mit Remotion/ffmpeg zusammensetzen.
• Um Fehlversuche zu vermeiden, beim ersten Test einen 5-Sekunden-Sample in 720 P rendern, um die Richtung zu bestätigen, dann die Parameter auf die tatsächlichen Anforderungen anpassen.
• Beispiel für Text-zu-Video (kostengünstiger Test, Dauer anpassbar):

bl video generate \
  --model happyhorse-1.1-t2v \
  --prompt "Helle, moderne Ausstellungshalle, ein intelligentes Gesundheitsgerät dreht sich langsam unter sanftem Licht, Business-Tech-Ästhetik, kein Text, kein Logo" \
  --ratio 16:9 \
  --resolution 720P \
  --duration 5 \
  --download public/assets/ai_device_5s.mp4

• Beispiel für Bild-zu-Video (kostengünstiger Test; lokale Bilder können direkt mit --image übergeben werden, CLI lädt automatisch temporäre Dateien hoch):

bl video generate \
  --model happyhorse-1.1-i2v \
  --image public/assets/device.jpg \
  --prompt "Behalte das Produktdesign bei, leichter Kamerazoom, sauberer Hintergrund, sanfte Reflexionen, kein Text" \
  --ratio 16:9 \
  --resolution 720P \
  --duration 5 \
  --download public/assets/device_i2v_5s.mp4

• Nach der Generierung mit ffprobe Dauer/Codierung prüfen; bei HEVC oder Browser-Inkompatibilität gemäß Schritt 4 nach H.264 konvertieren.

6. Text verfassen + Alibaba Bailian Sprachausgabe (bevorzugt)

• Den Voice-Over-Text in narration.json schreiben: {"s1":"...","s2":"..."}, die Schlüssel entsprechen den Storyboard-Abschnitten und müssen mit Narration file="s1.mp3" übereinstimmen. Komma-getrennte Sätze helfen der TTS, natürliche Pausen zu machen.
• Bevorzugt: Bailian CosyVoice:

source ~/.claude/skills/product-promo-video/config/bailian.env
python3 ~/.claude/skills/product-promo-video/scripts/gen_tts_bailian.py \
  --script narration.json --out public/audio

• Bei direkter CLI-Nutzung für einzelne Sätze:

bl speech synthesize \
  --text "Ein Satz Produkt-Promo-Voice-Over" \
  --voice longanwen_v3 \
  --language zh \
  --instruction "Business-Tech-Promo-Voice-Over, selbstbewusster, klarer, warmer Ton, mittleres Sprechtempo" \
  --format mp3 \
  --out public/audio/s1.mp3

• Volcengine als Alternative:

source ~/.claude/skills/product-promo-video/config/volcano.env
python3 ~/.claude/skills/product-promo-video/scripts/gen_tts_volcano.py \
  --script narration.json --out public/audio

• Bei Fehler code 3001 resource not granted = Konto nicht autorisiert: In der Volcengine-Konsole „Sprachsynthese“ aktivieren, die Stimme zur App-ID hinzufügen, App-ID/Token-Paar prüfen. Die erste Anfrage kann selbst nach Aktivierung fehlschlagen; das Skript hat bereits integrierte Wiederholungen. Einzeln fehlgeschlagene können einfach erneut ausgeführt werden.
• Fallback bei fehlender Netzwerkverbindung/Berechtigung: scripts/gen_tts_say.sh narration.json public/audio (macOS say, durchschnittliche Qualität, als Platzhalter).
• Large-Model-Stimmen (natürlicher, empfohlen): Bei Verwendung von *_bigtts / saturn_* / *_uranus_* etc. über die v3-Schnittstelle: source config/seed.env dann python3 scripts/gen_tts_seed.py --script narration.json --out public/audio. Stimmenwechsel durch export SEED_SPEAKER=<Stimm-ID>. Authentifizierung über API-Key (X-Api-Key), Streaming-Rückgabe, separates Dienst-/Abrechnungssystem von v1 (BV-Stimmen).
  • Resource-Id: seed-tts-2.0 (Standard in seed.env). Getestet: saturn_* und *_uranus_* laufen darüber; bei falscher Angabe (z. B. seed-tts-1.0/volc.megatts.default) erscheint Fehler code 55000000 resource ID is mismatched with speaker.
  • Netzwerk-/Proxy-Schwankungen können sporadisch RemoteDisconnected verursachen; das Skript hat integrierte Ausnahmebehandlung + Wiederholungen (--retry 5).

7. Szenenlängen an tatsächliche Audiodauer anpassen (kritisch, sonst Abschneiden)

~/.claude/skills/product-promo-video/scripts/measure_audio.sh public/audio

In SCENE_FRAMES in theme.ts sicherstellen, dass für jeden Abschnitt gilt:

Szenen-Frames ≥ delayFrames der Narration + ceil(Audio-Sekunden × fps) + Schluss-Leerraum (mind. 15 Frames empfohlen) Nach Änderung der Dauer gleichzeitig die Gesamt-Frames in Video.tsx prüfen (wird automatisch summiert, normalerweise keine Anpassung nötig).

8. Stilvorlage anwenden / Storyboard-Komponenten schreiben

• Bevorzugt: Vorgefertigte Stilvorlage verwenden (styles/STYLES.md). Die theme.ts, Dekorationsmodule und AllScenes.tsx des gewählten Stils in die entsprechenden src/-Verzeichnisse kopieren, dann die Texttafel-Inhalte an das aktuelle Drehbuch anpassen. Drei Vorlagen: warm/guochao/tech.
• Bei manuellem Schreiben/Feinabstimmen des Storyboards: BigTitle (große Texttafel), KenBurns, Subtitle, PhoneMock (unterstützt crop), Chip, FeatureCard aus components.tsx verwenden; für Guochao/Tech zusätzlich entsprechende Dekorationen (Siegel/Glaskarten/Eckenmarken/HUD) hinzufügen.
• In jeden Abschnitt ein <Narration file="sX.mp3" delayFrames={..} /> setzen.
• Ungünstige Daten überdecken: Auf dem entsprechenden PhoneMock eine React-Karte platzieren (siehe Beispiel MedsBadge).

9. Hintergrundmusik

python3 ~/.claude/skills/product-promo-video/scripts/gen_bgm.py \
  --duration <Videosekunden + 2> --out public/audio/bgm.mp3   # Optional: --semitones für Transposition --gain für Lautstärkeanpassung

Video.tsx hat bereits <BgMusic base={0.85} />, blendet automatisch über die Videolänge aus und wird unter das Voice-Over gemischt. Bei zu lautem Effekt base verkleinern.

10. Rendern + Selbstkontrolle

npx remotion render Promo "out/<Filmname>.mp4" --concurrency=2
~/.claude/skills/product-promo-video/scripts/verify.sh "out/<Filmname>.mp4"

• --concurrency=2 verwenden: Hohe Parallelität (4) kann auf lokalen Maschinen zu sporadischen Node-Abstürzen führen (Ausgabe endet mit Node.js v22.x-Stack-Trace, kein fertiges Video). Bei Absturz Parallelität reduzieren und im Vordergrund erneut ausführen; meist erfolgreich.
• Bei Hintergrund-Rendering kann ein Absturz auch mit exit 0 enden: Unbedingt prüfen, ob die MP4 in out/ tatsächlich erzeugt wurde, nicht nur auf den Exit-Code achten.
• Dann mit Read die Frames aus /tmp/vchk ansehen (Chinesisch/Emoji/Layout prüfen), die Lautstärke aus verify.sh checken (Mean etwa -18 dB bis -23 dB normal, darf nicht stumm sein). Bei Bedarf mit silencedetect prüfen, ob ein Voice-Over-Satz vollständig ausgesprochen wurde.

11. Auslieferung und Varianten

Pfad/Spezifikationen/Dauer des fertigen Videos angeben. Häufige Ergänzungen: Einbetten von Live-Action-Kurzvideos, Hochformat-Version (Breite/Höhe in Root.tsx anpassen + Layout neu ordnen), Text/Farben/Musik ändern und erneut rendern. Alternativ kann mit npm run dev das Remotion Studio zur Echtzeitvorschau geöffnet werden.

Harte Fallstricke (unbedingt beachten)

• Voice-Over muss in <Sequence from={delayFrames}> platziert werden. Nicht if(frame<delay) return null zum „Verzögern“ verwenden – das verzögert nicht den Start, sondern überspringt die ersten delay Sekunden des Audios, was die Anfangswörter verschluckt (typisches Symptom: „Mamas Medikament“ wird nur zu „Medikament“). Die Narration-Komponente in der Vorlage ist bereits korrekt implementiert.
• HEVC-Videos zuerst nach H.264 konvertieren, dann <OffthreadVideo> verwenden, sonst Chromium-Rendering schwarzer Bildschirm/Fehler.
• Material mit ASCII-Dateinamen in public/assets ablegen, mit staticFile('assets/xx.jpg') referenzieren.
• Chinesische Schriftart: @remotion/google-fonts/NotoSansSC verwenden (in der Vorlage theme.ts bereits konfiguriert, Fallback PingFang). Farbige Emojis werden in Chromium korrekt gerendert, können bedenkenlos als Icons verwendet werden.
• Nach der Sprachgenerierung unbedingt die Dauer neu messen und SCENE_FRAMES anpassen – verschiedene Stimmen/Sprechgeschwindigkeiten ändern die Dauer, sonst werden die Endlaute abgeschnitten.
• 5-Sekunden-Sample nicht als Produktionslimit betrachten. Die --duration der HappyHorse-Ergänzung richtet sich nach Benutzeranforderung, Budget und Modellunterstützung; längere Filme können aus mehreren KI-Clips, echtem Material und Remotion/ffmpeg zusammengesetzt werden.
• KI-Video-Prompts ohne Text/Logo formulieren, sonst werden leicht falsche Zeichen oder verzerrte Logos generiert. Markennamen, Verkaufsargumente und Untertitel immer mit Remotion überlagern.
• Volcengine 3001 ist meist ein Konto-Autorisierungsproblem, kein Code-Problem; gemäß Schritt zur Sprachausgabe prüfen.
• Volcengine-Zugangsdaten in config/volcano.env (enthält Schlüssel, nicht weitergeben); Secret Key wird für diese HTTP-Schnittstelle nicht benötigt.
• Alle Remotion-Pakete müssen exakt dieselbe Version haben (remotion / @remotion/cli / @remotion/transitions / @remotion/google-fonts alle 4.0.xxx ohne ^). Ein Caret führt dazu, dass ein Unterpaket eine neuere Version bekommt und ein Fehler wie export 'HtmlInCanvas' was not found in 'remotion' beim Bundling auftritt. Die Vorlage ist bereits fixiert; nach dem Hinzufügen neuer Pakete mit node -e "..." die Versionen auf Konsistenz prüfen.

Datei-Übersicht

• scripts/gen_tts_bailian.py – Alibaba Bailian CosyVoice TTS (bevorzugt, nutzt bl speech synthesize)
• scripts/gen_tts_volcano.py – Volcengine Standard-TTS (BV-Stimmen, v1-Schnittstelle, liest Zugangsdaten aus env, Text aus JSON)
• scripts/gen_tts_seed.py – Volcengine Large-Model-TTS (bigtts/saturn/uranus-Stimmen, v3-Schnittstelle, API-Key-Authentifizierung, empfohlen)
• scripts/gen_tts_say.sh – macOS-Offline-Notfall-Sprachausgabe
• scripts/gen_bgm.py – Generiert einfühlsame Hintergrundmusik
• scripts/measure_audio.sh – Misst Voice-Over-Dauer in Frames, kalibriert SCENE_FRAMES
• scripts/verify.sh – Selbstkontrolle des fertigen Videos (Spezifikationen/Lautstärke/Frame-Extraktion)
• config/bailian.env – Bailian TTS-Parameter · config/volcano.env – Volcengine Standard-TTS-Zugangsdaten · config/seed.env – Large-Model-TTS-Zugangsdaten
• config/narration.example.json – Beispieltext für emotionale Erzählung · config/narration.corporate.example.json – Beispieltext für Unternehmens-Produktvorstellung
• styles/STYLES.md + styles/{warm,guochao,tech}/ – Drei Stilvorlagen (Farbschemata + Dekorationen + Storyboards); nach Auswahl in das Projektverzeichnis src/ kopieren
• template/ – Direkt mit cp -R kopierbares Remotion-Projektgerüst