csm-kr/reference-motion-video

Reference motion video

Der Film ist HTML, und seine Cue-Liste ist die Partitur. Jedes sichtbare Ereignis registriert einen Cue neben der Konstanten, die das Bild bewegt; jeder Abschnitt des Films ist ein nach seinem Zweck benannter Bereich. Eine Palette verwandelt diese in Musik, die jedes Bild trifft und die Geschichte erzählt: kein Rhythmus, während das Problem beschrieben wird; ein Groove, wenn das Produkt funktioniert; ein Atemzug vor dem Höhepunkt; Drums aus, wenn das Produkt bewusst stoppt; ein absoluter Stillstand auf dem Logo.

Ausgeführte Beispiele: examples/claude-code/ (ausführbare Launch-, Erklär- und Demo-Filme auf einer gemeinsamen Bühne, jeweils mit einer anderen Palette), examples/moments-v2.html (36 s Continuous-Shot-Werbung), examples/ads/ (Moments-Werbung: Drums, Orchester, Violine). Die Moments-Kompositionen benötigen Produkt-Assets und Pfadanpassungen; sie sind Referenzen, keine rendergerfertigen Demos.

Regeln, die bisherige Filme bestimmt haben

1. Passform zuerst. Die Musik muss zur Stimmung des Produkts passen und den Bildfluss nachspielen. In einem blinden A/B-Test (KIBO v4.5, 30 s, gleiches Bild, gleiche Lautheit) wählte der Besitzer die auf das Bild komponierte Partitur gegenüber einem freien Electropop-Track, der beat-gematcht und in allen Maschinenmetriken besser war: „Der zweite passt nicht.“ Komponieren ist die Voreinstellung; ein Library-Track nur, wenn der Benutzer den Track auswählt (references/music.md).
2. Ein Sound auf jedem Cue, auf seinem Frame. Schnitte landen auf dem Beat, Wörter knallen auf dem Off-Beat, die größte Enthüllung bekommt den größten Schlag.
3. Nur echte Aufnahmen und echte Ausgabe. Bewegungsgrafiken rahmen ein und erklären, sie täuschen nie eine Funktion vor. Beschleunigungen und Warte-Schnitte auf dem Bildschirm kennzeichnen („Live-App · 1ד, „⋯ Warte-Schnitt“, „▶▶ beschleunigt“), synthetische Stimmen kennzeichnen, eine Quelle unter jede Zahl setzen.
4. Sprache zuerst. Wenn es eine Erzählung oder einen Dialog gibt, weicht das Bett aus (references/music.md, „Mix“).
5. Maschinelle Prüfungen sind notwendig, nicht hinreichend. Sync, Lautheit und STT können alle bei Musik bestehen, die nicht passt. Die Person entscheidet durch blindes Hören.
6. Fragen, dann entscheiden. Frage nur das, was die Anfrage und das Repository nicht beantworten können, mit einer empfohlenen Antwort zuerst; entscheide den Rest und teile dies mit.

Arbeitsablauf

0. Setup-Überprüfung (vor allem anderen)

Melde jede Zeile als ok oder fehlend, mit der Korrektur; gib niemals den Wert eines Schlüssels aus.

• Google Chrome (der Renderer steuert das installierte Chrome: das gebündelte Chromium kann H.264 nicht decodieren), ffmpeg (mit rubberband), Node ≥ 20 mit npm ci --prefix engine --ignore-scripts aus dem Skill-Verzeichnis.
• Python 3.12 mit numpy, scipy, soundfile, pytest (uv venv --python 3.12 .venv, dann uv pip install --python .venv/bin/python -r requirements.txt aus dem Skill-Verzeichnis).
• Samples: führe bash engine/fetch_samples.sh core aus (VSCO-2-CE CC0 Percussion, Blech, Schlägel; Pixabay-lizenzierte SFX), dann bash engine/fetch_samples.sh piano für soft_pulse (Salamander Grand Piano, CC-BY 3.0; bei Verwendung angeben). Paletten fallen auf Synthese zurück, wenn ein Sample fehlt, aber der Piano-Fallback kann die Abschnitts-Gleichgewichtsprüfung fehlschlagen lassen; verwende beide Sets für die vollständige Testsuite.
• Ein Erzähler-Dienst und seine Anmeldeinformationen nur, wenn eine Erzählung angefordert wird (references/voice.md). Für die drei lauffähigen Beispiele ist kein API-Key erforderlich. Erzählungs-, Transkriptions- und App-Capture-Clients sind nicht enthalten; verwende verfügbare Tools und überprüfe die aktuelle Dokumentation des gewählten Anbieters, wenn nötig.
• Freier Speicherplatz: Renderings leiten Frames per Pipe (keine PNG-Dumps), aber Sample-Bibliotheken und Takes benötigen einige GB.

1. Aufnahmegespräch → Einseitiges Briefing (vor der Planung genehmigt)

Frage nur nach Kontext, den die Anfrage und das Repository nicht liefern. Verwende das Umgebungs-Frage-Tool oder normales Chat, wenn keines verfügbar ist; gruppiere verwandte Fragen, setze die empfohlene Option zuerst und verwende bereits gegebene Antworten wieder:

1. Zweck: welche Art von Film (Launch, Konzept-Erklärer, Demo-Walkthrough, Anwendungsfall-Vignette, Manifest), wer sieht ihn, wo wird er veröffentlicht (YouTube, ein Wettbewerb, Social), was die Zuschauer danach tun sollen, das Abgabedatum und etwaige Bewertungskriterien.
2. Botschaft und Beweise: der eine Satz zum Merken, drei Beweise mit ihren Quellen, was nicht gesagt werden darf.
3. Form und Klang: Länge und Formate (16:9, 9:16, Cutdowns), Sprachen für Bildschirm, Untertitel und Stimme; Musik-Referenzlinks oder eine Stimmung (biete die Paletten aus der untenstehenden Tabelle an, die zum Zweck passen, plus „Ich habe Referenzlinks“); Erzählung oder nicht, und welche Stimme.
4. Quellen und Regeln: Kann die echte App aufgenommen werden (URL, Login, Demo-Daten, zwei Geräte), werden Personen erscheinen, Marken-Assets, Wettbewerbsregeln, IP Dritter. Lies das Briefing vor und hole ein Ja. Schreibe es in video/BRIEF.md.

2. Genre und Referenzen

Wähle die Beat-Vorlage des Genres und die gemessenen Ziele aus references/genres.md (16 offizielle Referenzen aus fünf Genres, mit Einstellungslängen, Wörtern pro Karte, Voice-Over-Tempo, wann das Produkt und das Logo erscheinen). Schaue dir die gewählten Referenzen mit /watch an; vermesse ihre Musik mit engine/ref-analyze.py. Für eine Continuous-Shot-Werbung lies references/transitions.md und references/youtube-analysis.md.

3. Plan → video/PLAN.md (vor dem Bau genehmigt)

Ein Beat-Sheet auf dem BPM-Raster (100 BPM = 0,6 s pro Beat, 18 Frames bei 30 fps; setze den Drop auf einen Downbeat): Zeit | Takte | Szene | Text auf Bildschirm | Filmmaterial | Abschnittsart | Cues | Stimme. Benenne das Heldenobjekt (ein Element des Produkts, das durch den Film reist und im Logo landet), den persistenten Frame und jede Behauptung mit ihrer Beweisddatei.

4. Echte Bildschirme aufnehmen

references/capture.md: wenn das Produkt es braucht, Live-Takes von zwei Geräten aus der echten App (CDP-Screencast-Frames mit Wanduhr-Stempeln, eine synthetische Kundenstimme, die in das Telefonmikrofon gespielt wird, die KI-Antwort von der Seite getippt), in MP4 mit konstanter Bildrate auf einer Uhr konvertiert, dann im Film durch eine Zeitkarte abgespielt ([[Film t, Take t], ...]: gleiche Schritte sind 1×, eine flache Linie ist ein Halten, zwei Punkte 1 ms auseinander sind ein Schnitt). Verwende das im Browser verfügbare Werkzeug; references/aside-capture.md gibt eine Aside-spezifische Implementierung. Terminal- oder Tool-Ausgabe: setze die echte Ausgabe neu (die Claude Code-Beispiele), erfinde sie nie.

5. Erzählung (optional)

references/voice.md: verwende den gewählten TTS-Anbieter oder bereitgestellte Aufnahmen, höre Takes an, wähle nach Wortgenauigkeit und Tempo (155-170 wpm ist ein Ausgangspunkt für eine englische Demo), und passe die Wortwahl oder Pausen an, bevor du die Sprache dehnst. Bereinige an der Quelle und schreibe jede Zeile in ein Wortbudget für ihren Slot.

6. Bau der Komposition

• Eine feste 1920×1080 #stage; alle Bewegung von EINER pausierten GSAP-Timeline; Tippen, Zähler, der Heldenpunkt und Video-Takes werden allein von der Zeit in __seek(t) ausgewertet. Keine CSS-Animationen, setTimeout oder requestAnimationFrame für Bewegung. fromTo benötigt immediateRender: false.
• Vertrag für die Engine: window.__duration, __seek(t), __ready, __cues, __sections, __bpm, __T. Beginne mit examples/claude-code/stage.js (Cues, Abschnitte, Wort-Pops, Tippen, Zähler, Terminalkarten, der Heldenpunkt) oder examples/moments-v2.html (virtuelle Kamera über echten Bildschirmen).
• Registriere einen Cue neben jeder Konstanten, die etwas sichtbar macht; markiere jeden Abschnitt mit einem Bereich nach Zweck (Tabelle unten).
• Untertitel: Reserviere einen lesbaren Slot für gesprochene Zeilen und halte andere Inhalte davon frei; identifiziere synthetische Sprecher und ihren Anbieter, füge Übersetzungen hinzu, wenn das Briefing sie erfordert, und schreibe die .srt aus derselben Untertitelliste.
• Prüfe Standbilder vor jedem vollständigen Rendering: node engine/stills.mjs index.html out/stills 1.7 3.6 ....

7. Musik: komponiere auf das Bild

node engine/cues.mjs > cues.json                      # dauer, bpm, T, cues, sections
python engine/compose.py cues.json score.wav --palette bright_demo [--narr narr.js --narr-root .]

compose.py schreibt die Partitur, mischt die Stimmen stimmenzuerst, mastered auf -14 LUFS (True Peak unter -1 dBTP) und führt die Sync-Prüfung selbst durch: ein Cue ohne hörbaren Einsatz innerhalb von 33 ms erhält den Betonungsklang der Palette und der Mix wird wiederholt (maximal zweimal); der Bericht listet, was hinzugefügt wurde. Höre vor der Auswahl: rendere denselben 15-30 s langen Abschnitt mit zwei oder drei passenden Paletten und lasse die Person blind auswählen. Details, Mix-Regeln und der Library-Track-Pfad: references/music.md.

8. Rendern

node engine/render.mjs index.html out/film.mp4 --fps 30 --audio score.wav (JPEG q95 Frames an x264 gepiped: etwa 10× schneller als PNG; YouTube-Flags: High Profile, GOP von der Hälfte der Bildrate, BT.709-Tags, AAC 48 kHz 384 kbps). Kurze Bereiche für Entwürfe: --from 10 --to 16. Chrome lädt etwa 18 verschiedene Videos in einer Seite; verwende Standbilder für Takes, die sich nicht bewegen.

9. Prüfungen (alle an den endgültigen Dateien)

references/qa.md. Überprüfe den Sync am endgültigen MP4 (python engine/synccheck.py out/film.mp4 cues.json: jeder Cue innerhalb von 33 ms, lese mit seiner Chance-Baseline), Lautheit, True Peak, Standbilder, Übergänge und das Urteil der Person beim Hören. Wende die Prüfungen für Stimme, Untertitel, QR und Revisionen nur an, wenn diese Funktionen vorhanden sind, und verwende dazu die im Werkzeug verfügbaren Tools; melde nicht durchgeführte Prüfungen nicht als bestanden. Ein Cloud-Verständnistest ist optional und erfordert die Wahl des Benutzers, den Film an diesen Dienst zu senden.

10. Ausliefern

Liefer die Länge und das Format des Briefings aus, normalerweise H.264 MP4, einen .srt-Begleitfilm, wenn Untertitel vorhanden sind, und ein Vorschaubild oder Cutdowns, falls angefordert. Die eingebaute Bühne und der Renderer sind 1920×1080; ein anderes Seitenverhältnis erfordert eine explizite Anpassung, kein Renderer-Flag. Berichte die tatsächlich durchgeführten Prüfungen und ihre Beweise. Die Veröffentlichung ist eine separate Aktion, es sei denn, der Benutzer hat dies bereits angefordert.

Abschnitte, nach Zweck

Art	Verwende sie, wo das Bild...	die Musik
intro	das Problem beschreibt, bevor das Produkt handelt	kein Rhythmus: nur ein Pad, die Cue-Sounds
tease	das Produkt aufweckt, die erste Frage	ein spärlicher Groove (kein Backbeat, keine Perkussion oder Melodie)
build	kurz davor ist, ein Ergebnis zu liefern; der Anstieg vor einem Wiedereintritt	ein Crescendo bis zum Ende des Abschnitts
groove	das Produkt bei der Arbeit zeigt (e 0.5-1.2)	der volle Groove bei Energie e
light	eine dichte Zeile oder eine Karte voller Text trägt	der Groove ohne seine Melodiefigur
muffled	eine ernste Tatsache, eine Statistik, ein Problem darlegt	der Groove tiefpassgefiltert, der in den nächsten Abschnitt öffnet
breath	für einen Beat vor dem Höhepunkt hält	fast Stille; nur der Sound des Heldenobjekts erklingt
stop	zeigt, wie das Produkt bewusst nicht handelt (ein Sicherheitsstopp, eine Grenze)	Drums aus, ein gehaltenes Pad
end	die Endkarte ist	Stille
riser (Überlagerung)	in eine Landung steigt	ein Riser, der am Ende des Abschnitts endet

Cue-Typen, die jede Palette beantwortet: drop (der Höhepunkt), reentry, final (das Logo, dann ein absoluter Stillstand), break (ein Stopp beginnt), cut (big für ein Kapitel), tap, tapTouch, pop, word, chip, node, num, count, fill, bar, key (Tippen), dot (der eigene Sound des Heldenobjekts).

Paletten (engine/palettes/)

Palette	Passt zu	Klang	Herkunft
bright_demo	Demo-Walkthroughs, freundliche Consumer- oder SaaS-Apps, stimmengeführt	F-Dur-Pop bei 100 BPM: knackige Kick, Clap und Snare, Shaker und Tamburin, Marimba (VSCO-Samples oder synthetisiert), zupfender Bass, luftiges Pad, Wassertropfen-Helden-Sound	KIBO v4.5 (A2-bright), Wahl des Besitzers; gewann den blinden A/B
drums_launch	Launch-Filme und Werbung, Produkt-Enthüllungen, musikgeführt	D-Moll-Live-Kit bei 100 BPM: VSCO-Kick, Snare und Ghosts, Hi-Hats, Congas, Kuhglocke, synkopierter Bass, gedämpfter Gitarren-Skank, Trompeten- und Horn-Stabs	Moments 50 s Drum-Werbespot (nach Apple's MacBook Air M5 Film), Lieblingsstil des Besitzers
soft_pulse	Konzept-Erklärer, Diagramme, erzählerlastige Filme	C-Dur bei 96 BPM: gesampeltes Piano, gestimmte Marimba-Cue-Sounds, weiches Kit, Bass und Pad; Schichten treten mit der Energie ein und Cue-Noten steigen, während ein Diagramm aufgebaut wird	für examples/claude-code/explainer

Weiterhin als eigenständige Skripte, die auf die Paletten-Schnittstelle portiert werden sollen: Piano und Glocken (engine/score.py, Moments v2), Band (engine/score_band.py, ein B2B-Promo), Orchester und Solovioline (examples/ads/orch, examples/ads/violin). Um eine Palette hinzuzufügen, folge engine/palettes/__init__.py und füge ihren Namen zu tests/test_compose.py hinzu: die Tests beweisen, dass sie die Abschnittsgrammatik ausführt (keine Kick im Intro, ein stiller Atemzug und Endkarte, Drums aus im Stopp, jeder Cue hörbar, -14 LUFS).

Dateien

• engine/: render.mjs, cues.mjs, stills.mjs, compose.py + palettes/, audio.py (Busse, Sampler, Raum), synccheck.py, beatmap.py und bedmix.py (der Library-Track-Pfad), ref-analyze.py, music-analyze.py, fetch_samples.sh.
• references/: genres.md, music.md, voice.md, capture.md, qa.md, transitions.md, youtube-analysis.md, aside-capture.md, ads/.
• tests/: python -m pytest -q tests/ (Beat-Map, Library-Mix, Sync-Prüfung, Abschnittsgrammatik auf jeder Palette).

Briefing- und Abgabebeschränkungen

• Verwende die angeforderte Dauer, Sprachen, Seitenverhältnis und Ziel. Überprüfe bei einem Wettbewerb die tatsächlichen Regeln und die Dauer mit ffprobe; übernimm keine Grenzen eines früheren Wettbewerbs.
• Zeige echtes Produktmaterial oder echte Ausgabe für Feature-Behauptungen und respektiere die Marken- und Asset-Berechtigungen des Benutzers. Kennzeichne inoffizielle Beispiele über ein anderes Produkt, wie es die Claude Code-Beispiele tun.
• Bereite zuerst lokale Liefergegenstände vor. Lade nur hoch, wenn der Benutzer das Ziel und die Sichtbarkeit autorisiert hat.