SuperAPI AI Directory

store-preview-videos

Coding & development

View repository

Updated 10-16 18:31

About this skill

Automate this: the recording and ffmpeg legs are fully automatable — run this skill directly, or /mobile-release:screenshots for the still set alongside it. No command covers the whole video path because two of its steps are human-only: real-device footage for a submitted preview, and the poster frame (skills/release-automation/references/human-only.md §7).

The two stores are not doing the same thing. Getting this wrong wastes the most time.

App Store app preview Play promo video
Deliverable A video file you upload A YouTube URL you paste [verified: Publishing API Listing.video is "URL of a promotional YouTube video for the app"]
Constraints 15–30 s, exact upload resolution per device class, H.264 or ProRes 422 HQ, ≤ 500 MB, ≤ 30 fps [verified] None on the file — YouTube's rules plus a short list of Play rules [snippet]
Source footage Must be captured from the app itself, "using footage captured on device" [verified] Anything you can put on YouTube
Count Up to 3 per localization [verified] One URL [verified]

There is no uploadable video asset for Play. If the task is "make a Play promo video", the deliverable is a YouTube link and the video behind it, not an .mp4 in a metadata folder.

Confidence marks used throughout this skill and its references: [verified] — read off a primary vendor source on 2026-08-05. [snippet] — secondary source only, plausible but unconfirmed. [unverified] — not confirmed anywhere; run the check given before relying on it.

Process:

  1. Establish the deliverable — file or URL. Re-read the table above.
  2. Apple only: look up the upload resolution for the device class. It is not the screenshot resolution and it is much smaller. references/apple-preview-specs.md.
  3. Record: iOS xcrun simctl io recordVideo --codec h264 --mask ignored, or QuickTime from a real device (2); Android adb shell screenrecord (3, references/android-recording.md).
  4. Cut to spec with ffmpeg — trim, normalise fps, scale to the exact target, H.264 yuv420p, handle audio. references/ffmpeg-video.md.
  5. Verify with ffprobe. Every rejection in the troubleshooting table is something ffprobe catches.
  6. Deliver — fastlane deliver for Apple, the YouTube URL field for Play. references/upload-and-rules.md.

Load only the reference you need.


Contents

  • 1. Apple's constraints
  • 2. iOS recording
  • 3. Android recording
  • 4. ffmpeg
  • 5. Delivery
  • Troubleshooting
  • Output Format
  • References

1. Apple's constraints

All [verified: Apple's app-preview specification page, fetched 2026-08-05]:

  • 15 s minimum, 30 s maximum. Poster frame defaults to 5 s.
  • Up to 3 previews per localization. Max file size 500 MB.
  • H.264: 10–12 Mbps, progressive, up to High Profile Level 4.0, max 30 fps; .mov, .m4v, or .mp4. ProRes 422 HQ is the only accepted alternative (VBR ~220 Mbps, .mov).
  • Audio, if present: stereo, 256 kbps AAC, 44.1 or 48 kHz, all tracks enabled.

Upload resolutions — the two that cover most apps; full table in references/apple-preview-specs.md:

Device class Portrait Landscape
iPhone 6.9" / 6.5" / 6.3" / 6.1" 886 × 1920 1920 × 886
iPad 13" / 11" / 10.5" 1200 × 1600 1600 × 1200

Content rules [verified: https://developer.apple.com/app-store/app-previews/], full list in the reference: footage must be captured on device and "must show only content within the app itself"; "don't film people interacting with a device" — no hands, no hardware, no external clips, use graphic touch hotspots instead; previews autoplay muted, so the video must work silent; no unlicensed music, seasonal references, or prices; changing the poster frame after approval requires resubmission.

Simulator caveat: Apple's wording is "captured on device". A simulator recording lacks real-device rendering artefacts and may be questioned [unverified — Apple does not explicitly ban the simulator]. Iterate on the simulator; submit real-device footage.


2. iOS recording

xcrun simctl boot "iPhone 17 Pro Max"
xcrun simctl status_bar booted override --time "9:41" \
  --dataNetwork wifi --wifiMode active --wifiBars 3 \
  --batteryState charged --batteryLevel 100 --operatorName ""

xcrun simctl io booted recordVideo --codec h264 --mask ignored --force preview.mov
# ... drive the app (Maestro flow, or by hand) ...  Ctrl+C to stop

Syntax [verified], flag semantics [snippet]: simctl io <UDID> recordVideo [--codec h264|hevc] [--mask ignored|alpha|black] [--force] <path>

  • --codec h264 is mandatory. The default is hevc [snippet] — omit it and you ship a file outside Apple's accepted codecs. This is the most common silent failure in the whole pipeline.
  • --mask ignored saves the unmasked framebuffer; alpha and black put transparency or black into the rounded corners.
  • Output is .mov. Apple accepts .mov/.m4v/.mp4, so converting is optional.

A 1320 × 2868 capture still needs resizing to 886 × 1920; the aspect delta is under 0.3 %, so a centre crop is imperceptible — see 4.

Real-device route, the one Apple names: QuickTime Player on a Mac with the device connected by cable. Click path in references/apple-preview-specs.md [unverified — Apple gives no steps].


3. Android recording

Play accepts no file, so this produces footage for YouTube (or any other use).

adb shell screenrecord --bit-rate 12000000 --time-limit 30 /sdcard/demo.mp4
# ... interact ...  Ctrl+C to stop early
adb pull /sdcard/demo.mp4 ./demo.mp4
adb shell rm /sdcard/demo.mp4

Flags and limits, all [verified: https://developer.android.com/tools/adb]:

  • --size WIDTHxHEIGHT — default is the device's native resolution (or 1280 × 720 if native is unsupported). It letterboxes or crops; it does not re-render the UI at that size.
  • --bit-rate RATE — pass bits per second (the docs say "megabits" but the documented example passes 6000000). Default 20 Mbps.
  • --time-limit TIME — seconds; default and maximum 180 (3 minutes). For longer footage, record several clips and concat them.
  • Audio is not recorded. Screen rotation during recording is not supported.
  • Records at device resolution by default, so the AVD or handset determines the output size.

Write to /sdcard and adb pull — there is no reliable exec-out streaming form [unverified]. --bugreport (timestamp overlay) is widely used but was absent from the official flag table [unverified]; check adb shell screenrecord --help, and never leave it on for a published video. Clean the frame first with SystemUI demo mode — see references/android-recording.md.


4. ffmpeg

Full cookbook in references/ffmpeg-video.md. The single command from a simctl capture to an App-Store-ready iPhone preview:

ffmpeg -i preview.mov -t 25 \
  -vf "fps=30,scale=886:1920:force_original_aspect_ratio=increase,crop=886:1920,setsar=1" \
  -c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p \
  -b:v 11M -maxrate 12M -bufsize 24M -movflags +faststart -an \
  preview_69.mp4

Then always — expect 886, 1920, 30/1, yuv420p, h264, duration 15–30:

ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate,pix_fmt,codec_name,duration \
  -of default=noprint_wrappers=1 preview_69.mp4

Every ffmpeg command in this skill is [unverified] as a whole line — the filter options behind them are [verified] from FFmpeg source, but none were executed. Run each once and check with ffprobe before putting it in a pipeline.


5. Delivery

  • App Store: fastlane deliver uploads previews alongside screenshots from the fastlane/screenshots tree — [verified] for screenshots, [unverified] for the preview filename convention, so confirm with fastlane deliver --help and the generated Deliverfile before scripting. Manual upload in App Store Connect is a fine fallback, and is where you set the poster frame regardless.
  • Play: paste the full https://www.youtube.com/watch?v=… URL into the listing, or write it to fastlane/metadata/android/<locale>/video.txt for supply [verified: supply's AVAILABLE_METADATA_FIELDS includes video].

Troubleshooting

Symptom Cause Fix
Rejected: wrong resolution Uploaded the screenshot size (1320 × 2868) instead of the preview size (886 × 1920) Scale + crop to the exact preview size
Rejected: unsupported codec recordVideo wrote HEVC, its default Re-record with --codec h264, or transcode with -c:v libx264 -profile:v high -level 4.0
Rejected: too long / too short Outside Apple's 15–30 s window -t 25; if the source is under 15 s, record more — do not loop or freeze-frame
Rejected: alpha channel --mask alpha/black, or an RGBA intermediate Re-capture with --mask ignored; encode -pix_fmt yuv420p
Plays fine locally, rejected on upload Frame rate above 30, or non-square SAR stretching playback fps=30 filter plus setsar=1
Rejected on audio Apple specifies stereo AAC 256 kbps at 44.1/48 kHz [verified]; whether a track is required is [unverified] Rejected with no audio → add a silent conforming track (anullsrc recipe in the reference). Rejected with audio → confirm stereo AAC 256 kbps / 48 kHz, not mono or 5.1
Play: video does not play in the listing Playlist/channel URL, youtu.be short link, private, age-restricted, non-embeddable, or monetized [snippet] Use the full watch?v= URL of a public, embeddable, non-monetized video
Play: video slot looks empty before tap Autoplay did not happen; Play falls back to the feature graphic [snippet] Upload a 1024 × 500 feature graphic
Preview shows hands or device hardware Violates "only content within the app itself" [verified] Re-capture on-device; use graphic touch hotspots

Output Format

Report the target spec, the produced file with its measured properties, and anything still blocking upload. Never report a file as done without running ffprobe on it.

Example output:

Target

App Store, iPhone 6.9" portrait — 886 × 1920, H.264, 15–30 s, ≤ 30 fps, ≤ 500 MB.

Produced

build/preview_69.mp4   886x1920   30/1   yuv420p   h264 High/4.0   24.9s   38 MB   OK
ffmpeg -i preview.mov -t 25 -vf "fps=30,scale=886:1920:force_original_aspect_ratio=increase,\
crop=886:1920,setsar=1" -c:v libx264 -profile:v high -level 4.0 -pix_fmt yuv420p \
-b:v 11M -maxrate 12M -bufsize 24M -movflags +faststart -an build/preview_69.mp4

Blocking

  • Source was simctl on iPhone 17 Pro Max. Apple asks for footage "captured on device" — re-record on a physical iPhone before submitting; this cut is fine for internal review.
  • Poster frame is still Apple's 5 s default, which lands on an empty search screen. Choose one in App Store Connect — it cannot be changed after approval without resubmitting.

Play

No file. Deliverable is https://www.youtube.com/watch?v=XXXXXXXXXXX — public, embeddable, not age-restricted, monetization off. Written to fastlane/metadata/android/en-US/video.txt.

End of example.


References

  • references/apple-preview-specs.md — full spec, upload resolutions for every device class, content rules, poster frame, real-device capture route, pre-upload checklist.
  • references/android-recording.md — screenrecord flags and limits, clean-frame setup, driving the app while recording, multi-clip capture past the 180 s cap.
  • references/ffmpeg-video.md — trimming, fps, scale/pad/crop to exact resolution, H.264 and ProRes, concat, audio strip/replace/silence, ffprobe verification.
  • references/upload-and-rules.md — fastlane deliver for previews, Play's YouTube URL rules, the supply video.txt path, side-by-side comparison.