How to Record iOS Simulator Video for App Store Previews

Why this happens

Creating App Previews for App Store Connect requires video captures that match the exact pixel dimensions of Apple display specifications (such as 886×1920 or 1290×2796 for modern iPhones). When developers attempt to capture these videos using Mac desktop screen capture tools or QuickTime screen recording, the resulting video matches the Mac display scaling rather than the virtual device’s native framebuffer.

On physical monitors with 1080p or standard Retina displays, large simulators (such as the 6.7-inch iPhone Pro Max or 12.9-inch iPad Pro) are automatically scaled down to fit on the screen. Capturing the macOS desktop area displaying the simulator scales down the pixels, producing videos with incorrect dimensions, blurry UI elements, and non-compliant aspect ratios that App Store Connect rejects immediately.

Additionally, standard screen recordings capture Mac cursor interactions, system alerts, and variable refresh rates. To produce an acceptable App Preview, video must be pulled directly from the Simulator framebuffer at 100% scale using Xcode’s integrated capture tools or the CoreSimulator command-line interface.

How to fix it

1. Record via the Simulator UI

Modern versions of the Simulator app include built-in screen capture features that pull frames directly from the simulated device buffer, ignoring your desktop monitor’s scaling settings.

1. Launch your app in the target device simulator inside Xcode.
2. In the Simulator menu bar, click File > Record Screen (or press Control + Command + R).
3. Perform the user flows you want to feature in your App Preview. A recording indicator appears in the Simulator title bar.
4. Click the Stop button in the title bar or press Control + Command + R again.
5. A thumbnail preview appears in the bottom right corner of your screen, similar to macOS screenshots. Right-click the preview to save it directly as an MP4 or drag it into your target project directory.

Holding Option while clicking File > Record Screen or right-clicking the thumbnail allows you to export directly to an App Preview-compliant format.

2. Capture native video using xcrun simctl

The command-line tool simctl communicates directly with the booted simulator daemon. It captures exact native device pixels to disk regardless of whether the simulator window is minimized, hidden behind other windows, or visually scaled to 33% on a smaller Mac monitor.

Open Terminal and identify your booted device:

xcrun simctl list devices | grep Booted

To start recording the active booted device, run:

xcrun simctl io booted recordVideo preview.mp4

Execute your test interactions inside the simulator window. When finished, return to Terminal and press Control + C. The command stops writing and finalizes the MP4 container in your current working directory.

If you have multiple simulators running at once, replace booted with the specific device UUID:

xcrun simctl io 7B81234E-1234-4567-ABCD-890ABCDEF012 recordVideo preview.mp4

3. Apply simctl flags for App Store Connect compliance

simctl io provides flags to enforce codecs, handle corner display masks, and overwrite existing output files without prompting:

xcrun simctl io booted recordVideo \
  --codec=h264 \
  --mask=ignored \
  --force \
  preview_app_store.mp4

These flags perform the following adjustments:
– --codec=h264: While HEVC (--codec=hevc) produces smaller file sizes, H.264 offers broader compatibility across older video pipelines and transcoders.
– --mask=ignored: Ignores the rounded corner cutouts and Dynamic Island overlays on modern iPhones, capturing the full rectangular framebuffer required by App Store Connect upload specifications.
– --force: Automatically overwrites any previous file with the same name in the output directory.

4. Normalize the Status Bar before recording

App Store Previews must show clean, standard status bar presentations (9:41 AM time, full cellular bars, full Wi-Fi, and 100% battery). You can override the status bar indicators globally using simctl before initiating your video capture:

xcrun simctl status_bar booted override \
  --time "9:41" \
  --dataNetwork wifi \
  --wifiMode active \
  --wifiBars 3 \
  --cellularMode active \
  --cellularBars 4 \
  --batteryState charged \
  --batteryLevel 100

Once your recording is finished, clear the overrides to restore live device status:

xcrun simctl status_bar booted clear

5. Add a silent audio track if uploads fail

App Store Connect requires video files submitted as App Previews to include an audio track. If your app produces no sound and simctl records a video-only stream, the App Store Connect validator may display an upload error.

You can use ffmpeg to append a silent stereo audio track without re-encoding the video stream:

ffmpeg -i preview_app_store.mp4 -f lavfi -i anullsrc=channel_layout=stereo:sample_rate=44100 -c:v copy -c:a aac -shortest final_app_preview.mp4

How to prevent it

• Do not use third-party screen grabbers or QuickTime macOS desktop recording to capture simulators, as they record display-scaled pixels rather than native device points.
• Always set --mask=ignored when capturing devices with curved screens or camera cutouts to avoid black corner artifacts in App Store Connect.
• Standardize the simulator status bar using xcrun simctl status_bar in a shell script prior to recording.
• Verify the exported file dimensions with ffprobe preview.mp4 or QuickTime Inspector (Command + I) before uploading to confirm they match App Store Connect target resolutions.

FAQ

Does resizing the Simulator window affect the recorded video resolution?

No. The Simulator window zoom level (e.g., 50% or “Fit to Screen”) only changes how the window renders on your Mac desktop. Both the Simulator Record Screen option and xcrun simctl io capture the native internal device framebuffer directly.

Why does App Store Connect reject the video for missing audio?

App Store Previews expect an audio track formatted in AAC or stereo LPCM. When capturing with simctl, if the app does not emit audio, the resulting container might lack an audio track entirely. Injecting a silent AAC track using ffmpeg resolves this issue.

Can I record an iPad simulator video using the same command?

Yes. xcrun simctl io booted recordVideo output.mp4 works across all iOS and iPadOS devices. The command pulls the native point scale of whatever device model is currently booted.