wbr664393425-lgtm/rui-ui-promo-video

Real Component Promo Video Workflow

Default Style = "One Line" : A brand motif from the product runs throughout the entire video, paired with white space and three highlights triggered by real interactions. See the creative playbook for comparison with structured instructional shots and stacked-effects show-style shots.

templates/ = Capture shell (generic, already patched with common pitfalls) + v3 final composition, styles, soundtrack, and export scripts. Copy to videos/<name>/ and edit positions marked 【MUST MODIFY】.

Read as needed:

• references/creative-playbook.md: Motif, three highlights, white space rules, copy, rhythm table. Must read before finalizing storyboard.
• references/compose-recipes.md: Coordinate mapping, time mapping, shot containers, light panels, stroke lines, spotlight, world flip, logo assembly, transitions, timeline writing. Read before composing.
• references/pitfalls.md: Phenomena → root cause → handling table and verification commands for shooting, rendering, audio, and delivery. Check when encountering anomalies.

Tech Stack

Component	Technology	Key Points
Composition/Rendering	HyperFrames (fixed [email protected], npx --yes, not installed as project dependency)	check validation, snapshot frame extraction, render output
Motion	GSAP (copy version from project to assets/vendor/gsap.min.js)	Register single paused timeline to window.__timelines[id]
Capture Build	Vite + @vitejs/plugin-vue (createRequire resolves dependencies from frontend project)	Independent root; envDir/publicDir points to frontend project; vendor chunked separately
Deterministic Clock	Vite transform plugin	All setTimeout/rAF/Date.now/performance.now calls (bare and window. prefixed) redirected to window.__shoot
Data Isolation	In-memory fixtureFetch (including write operation simulation) + network whitelist + fixed seed + fixed epoch + fixed positioning	Fictional data, business requests go through fixtures, fixed capture clock
Interaction Script	performActions(t) + once/byText/rowButton/typeInto	Drives real clicks, input, and drags at specified seconds
Materials	Landscape PROMO_RESOLUTION=4k 2x pixel density; phone 430×932 separate viewport	Composition can push in significantly while remaining sharp
Soundtrack	Python3 + NumPy (96 BPM, FFT reverb, fixed seed)	Silent downbeats, heavy accents on highlights, node activation chimes
Loudness/Export	FFmpeg two-pass loudnorm (−14 LUFS / TP −3), normalized original soundtrack, compressed version, cover	Main + -share.mp4 (≈11 MB) + cover PNG

Directory Structure

videos/<name>/
  promo.config.mjs   appDir/srcDir/entry/motionFile/id/duration/coverAt/hyperframes — only project-related config
  capture/           index.html (capture shell) bootstrap.ts (clock/isolate/interaction) fixtures.ts (fictional data, needs new write) vite.config.mjs
  scripts/           render-footage.mjs compose-film.mjs compose-audio.py normalize-audio.mjs render-film.mjs remux.mjs
  assets/            footage/ footage-4k/ audio/score-final.wav vendor/gsap.min.js
  index.html (generated by compose) film.css package.json README.md

npm scripts: capture / compose / audio / check / snap -- <seconds,seconds> / render / remux / dev.

Workflow

1. Set Direction: Read PRODUCT.md/DESIGN.md/brand identity, find motif and design three highlights according to creative-playbook. Only confirm two things with the user: creative direction (give 2–3 options, recommend "One Motif"), copy tone (keep or refresh).
2. Storyboard: Each scene = real page + one Songti serif title + key interaction seconds + motif form in this scene; 45s reference rhythm in playbook. Write into README storyboard table.
3. Capture Shell: bootstrap.ts hooks window.__shoot, network whitelist, fixed positioning, clear storage (including IndexedDB drafts), preset theme/view/offline token, replaceState to route then import product entry; slow loading pages use waitFor/settle to flush rAF; inject hidden cursor/scrollbar/insertion point styles. fixtures.ts fields follow real API, write operations only in memory. Preview interactions in browser with ?shot=<scene>&live.
4. Capture: npm run capture (single worker); for landscape shots with large push-ins, also run PROMO_RESOLUTION=4k npm run capture.
5. Measure Coordinates: Extract frames from materials (1920 coordinates, 4K local crop for precise values) to measure trajectory polylines, buttons, popups, step node positions.
6. Composition: Edit compose-film.mjs segment table, coordinates, copy, time points; reuse its utility functions; rules in compose-recipes. Each round: npm run compose && npm run check, then npm run snap -- <key seconds> to view contact sheet (highlight entries/exits, transitions, annotation alignment).
7. Soundtrack: Edit compose-audio.py time points (highlight heavy accents, silent sections, clicks, node chimes), npm run audio.\n8. Render & Validate: npm run render runs in background; after completion, use ffprobe to verify duration/frames/resolution/framerate, use ebur128 for loudness and true peak, run blackdetect (explain intentional black frames), and extract ~18 frame collage for visual inspection. To only replace cover, run npm run remux.

Constraints

• Product source code and dependencies are not modified; clock rewriting happens only in the capture build.
• Use only fictional data; do not connect to business backend/database or read real credentials; third-party online resources (e.g., maps) use whitelist, API keys go only into ignored build directories. README clearly documents isolation method, seed, and fixed date.
• Annotations only use numbers that actually appear in the UI; no "demo/sample/mock" text in visuals or copy.
• Visuals follow project DESIGN.md and brand colors; fonts declared locally (Songti SC / PingFang SC / Georgia).
• Intermediate artifacts (.capture-build/ .shots/ .quality/ renders/ logs) go to .gitignore; old versions kept untouched, new versions in separate directories.
• Do not commit or publish to external platforms unless explicitly requested by the user.
• Before writing or modifying composition, call hyperframes-core, hyperframes-animation, hyperframes-cli as needed to verify current API.

Delivery Checklist

• Main MP4 (45.000 s / 2700 frames / 1920×1080 / 60 fps / H.264 yuv420p / AAC 320k 48 kHz / −14 LUFS / True Peak ≤ −1 dBTP).
• Share version -share.mp4 and cover PNG, delivered via the file delivery method supported by the current platform.
• Editable index.html + film.css, as well as materials and scripts.
• README: visual description, storyboard table, soundtrack description, reproduction commands, capture isolation, delivery verification.