App Preview Video

App Preview video for the app in this repository

The end state: one MP4 per preview board under osg/out/, 886x1920, H.264, no audio track, between 15 and 30 seconds, built from real captured footage of the app, listed in osg/osg.manifest.json and accepted by App Store Connect.

The rule that governs everything here

Apple Review Guideline 2.3.4: an App Preview may only use video screen captures of the app itself. Not a mockup, not an animated design, not a montage of stills. The same guideline explicitly allows narration and video or textual overlays to explain what the footage does not.

That is why this pipeline has three modes and only two of them can be uploaded to the App Store.

styled is a good asset and a bad submission. If the user asks for "a video for the store", produce store-text and say why. If they ask for "a video for the website", produce styled.

Step 0: doctor first, because of one trap

npx -y open-screenshot-generator@0 doctor

MP4 export needs a branded browser. The encoder is WebCodecs with an avc1 (H.264) profile, and H.264 is a proprietary codec that plain Chromium and Chrome for Testing do not ship. PNG export, the 49 design tools and the AI agent work on any Chromium. Video does not. So:

• Chrome, Edge or Brave: works.
• Chromium from a distro package, or the build osg doctor --install-browser fetches: VideoEncoder reports no supported H.264 config and the render fails with a "use Chrome or Edge" message. There is no fallback encoder.
• Point at a branded build with --browser "C:/Program Files/Google/Chrome/Application/chrome.exe" or --browser /usr/bin/google-chrome-stable, or set browser in osg/osg.config.ts.

doctor probes this per browser and says so, rather than assuming. Do not start a capture session before it passes.

Step 1: get real footage

osg does not record your app. Capture it with the platform's own tooling:

xcrun simctl io booted recordVideo --codec h264 osg/media/demo.mov
adb shell screenrecord /sdcard/demo.mp4 && adb pull /sdcard/demo.mp4 osg/media/demo.mp4

Rules that come from the compositor, not from taste:

• Record the Release build. A dev banner in the footage is a rejection and a bad ad.
• Record one continuous journey, not a montage: open the app, start the core action, finish it, see the result. The cut has to read on its own without narration.
• A phone records at 1290x2796 and that is fine. The export cover scales and centers to 886x1920, so a portrait recording fills the frame edge to edge.
• Record 20 to 40 seconds and trim, rather than recording exactly 18 and finding a stumble in it.
• No audio is used. The MP4 has a video track only, so nothing you say into the recording survives.

Put the file path in video.recording in the config. The CLI serves it to the page over the local origin, so a large file never has to travel as base64.

Step 2: start from a preview scene, not from an empty board

There are 20 finished App Preview scenes, each a whole board: background, phone mockup playing the recording, timed copy, gesture hints and a call to action, arriving 18 seconds long, already inside Apple's 15 to 30 second window. Building the same thing from add_elements plus set_animation is several times the work and rarely as good.

npx -y open-screenshot-generator@0 edit --script osg/preview.json

[
  { "tool": "list_preview_scenes", "args": { "query": "finance" } },
  { "tool": "add_preview_scene", "args": { "sceneId": "spotlight-launch" } },
  { "tool": "get_artboard", "args": {} }
]

Scene ids include spotlight-launch, feature-rush, headline-punch, five-star-proof, three-taps, money-mode, sweat-session, calm-hour, night-feed, order-up, trip-ready, beat-drop, learn-streak, shop-drop, focus-block, snap-fix, team-sync, health-check, play-now and home-control. list_preview_scenes is the live list.

Preview scenes are not in osg templates or in list_templates: that catalog deliberately hides the app-preview category, because those boards play a recording. list_preview_scenes is the door.

The get_artboard call at the end is not optional. It returns the layer ids and names you need next, and a model cannot see the canvas.

Step 3: put the footage in the phone

The recording is not an image asset. upload_asset probes bytes with an <img> and refuses a video, and its asset: references get expanded into data URLs, which would inline tens of megabytes into the saved project. Recordings stay blobs and elements carry only a media id.

[
  { "tool": "upload_recording", "args": { "source": "https://example.com/demo.mp4", "name": "demo" } },
  { "tool": "update_element", "args": { "elementId": "phone", "mediaId": "<the id it returned>" } }
]

source takes an http(s) URL the page can fetch, a data:video/... URL, or bare base64. Prefer a URL for anything large: a request body is capped at 32 MiB. The layer to target is the one named "Phone (drop your recording here)".

Use the config for a local file. osg video reads video.recording, publishes that file on the CLI's own local origin, and hands the page a URL, so a 90 MB .mov on disk never has to be encoded into a JSON body. Reach for upload_recording by hand only when you need two different clips on two boards.

Trim inside the element rather than re-recording: trimStart and trimEnd are seconds into the source, on the video-device layer.

Step 4: rewrite the overlays and check the timeline

Rewrite every placeholder string with update_element. Overlay copy is not the same as screenshot copy: it has to be readable in under two seconds, over moving footage, at phone size. Three to five words. One idea per overlay.

Timing lives in set_animation:

• Presets are fade, slide-up, slide-down, slide-left, slide-right, scale-up, pop.
• enterDelay is the second the entrance starts, enterDuration defaults to 0.6.
• An exit needs exitStart, an absolute second. Without it the layer never leaves, and an exitStart before the entrance lands is rejected rather than stored.
• Animations only play in the exported MP4 and in the timeline player. On the canvas and in a PNG every layer is drawn at rest, all at once, so two layers must never share a position and take turns in time. That looks right in the video and like a smear everywhere else.
• set_animation refuses recordings and gestures on purpose. A recording always starts the board (trim it), and a gesture is timed by triggerTime and gestureDuration.

Gesture hints are their own element type: tap, double-tap, swipe-left, swipe-right, swipe-up, swipe-down, placed over the point in the footage where the finger goes, with triggerTime matched to the moment the recording shows the interaction. gestureRepeat loops it for the whole board.

Then read the board back as data before you spend minutes on a render:

[{ "tool": "get_preview_timeline", "args": {} }]

It returns the board length, one clip per layer, and a list of what will bite at export: a board under Apple's 15 second floor, a layer animating past the end, or no recording in the phone yet. set_preview_duration sets the board length explicitly, 15 to 30 for the App Store, and seconds: null hands it back to whatever the content works out to.