Justice219/mobile-app-cinematic-video

Mobile app cinematic video

Turn a real app workflow into a directed 3D film using the included Three.js, Playwright, FFmpeg, and Python production template. This is an editable code-based video workflow, not an After Effects project.

Start from the app and existing direction

• Inspect existing exports, project source, current user feedback, actual runtime theme, and available app data before authoring. Preserve approved choices. For a new project, establish the demonstrated feature, audience, format, and available captures.
• Capture real app components using fictional fixtures or authorized recordings. Measure actual tap targets, scroll offsets, and highlighted bounds. Never replace real feature behavior with invented screens and call it authentic. Label staged native-only visualizations in delivery provenance.
• Match runtime colors. The included sample palette is only a default; it is not another app's brand. Dark mode throughout, sparse editorial text, and a phone-exit/brand reveal are the originating project's preferences, configurable when the user asks otherwise.

Production sequence

Read references/workflow.md for the production method and fragile timing/geometry details. Read references/capture.md when making or updating screen captures. Read references/timeline.md when authoring actions, camera poses, scrolling, or text.

1. For a new project, run python3 scripts/scaffold.py /absolute/new/project from this skill folder. It copies assets/template and creates clearly labeled synthetic demonstration screens. Replace those screens before a real deliverable. For an existing film, edit its project directly rather than scaffolding again.
2. In the generated project install Node/Python dependencies and Chromium as documented in the repository README. Set project.json from the actual app theme, optional owned fonts, and brand image/crop. The current renderer targets 1080×1920 at 30 fps, with 430×860 CSS app captures at DPR 3; changing aspect ratios requires coordinated geometry and coordinate changes.
3. Capture the workflow and write source/films.json. Use one primary camera action at a time, fast tactile feedback, and clear setup → action → result beats. Keep the narrated feature visible when spoken. Use short added text for emphasis; sidecar captions are a separate deliverable.
4. Write source/narration.json and generate missing narration with python3 source/narrate.py only when voice generation is authorized. Supply ELEVENLABS_API_KEY and ELEVENLABS_VOICE_ID through the process environment. Cache the MP3/alignment pair; never put secrets into source, screenshots, logs, or ZIPs. Failed paid requests stop without automatic retry. Use cached audio for iteration.
5. Use the returned character timestamps plus the 0.65-second mix offset to direct highlights, taps, camera focus, text, and ending. Render preview frames, inspect them, then render the film. The template supports --preview, --only INDEX, and --manifest PATH; mix/verify/package use source/films.json.
6. Run python3 source/mix.py. Prefer authorized sound-library samples in assets/audio/sfx; absent samples use original procedural fallbacks. Keep effects intelligible under voice. The template aligns transient peaks to actions and ducks effects under narration.
7. Run python3 source/verify.py, inspect critical transitions and narrated moments visually, and listen to the final mix. Automated dark-frame/loudness checks do not establish that the correct feature is shown. Review subtitles and all promised text.
8. Run python3 source/package.py after exports pass. Inspect the archive's explicit contents and media rights before sharing. Deliver MP4, optional SRT/VTT, previews, editable source, and provenance. Publishing, deployment, and posting remain within the user's requested scope.

Preserve these invariants

• App texture uses sRGB and toneMapped:false; scene lighting must not recolor the app.
• Highlights and scroll pixels use the same measured scroll interpolation. An atlas remains active after scrolling finishes; otherwise short scroll durations can expose a blank region.
• Camera focus is computed before the exit transform so the camera does not follow the departing phone. Begin the brand reveal promptly during the closing narration; do not leave a dead hold.
• World-space particles have depth testing and perspective sizing. Keep them subordinate to app content.
• Use the GPU explicitly on macOS (--enable-gpu --use-angle=metal), render deterministic times frame / 30, and pipe frames with backpressure into FFmpeg.
• Do not copy credential files, proprietary application source, unlicensed fonts/SFX, or customer data into a reusable skill or public repository.

The optional scripts/demo_audio.py creates a synthetic tone for an offline pipeline smoke test. It is explicitly not narration and must never be passed off as a finished voice-over.