iOS Simulator camera poster¶
The iOS Simulator has no camera. AutoMobile injects a still-image capture pipeline into
simulator app processes for startDevice cameraPosterPath / cameraPosterQr and
setDeviceState cameraPoster. Source: ios/CameraPosterInjection/.
Approach¶
AutoMobile activates the library by launching the app with
SIMCTL_CHILD_DYLD_INSERT_LIBRARIES=<libAMCameraPoster.dylib> and one of SIMCTL_CHILD_AM_CAMERA_POSTER_PATH=<png|jpeg> / SIMCTL_CHILD_AM_CAMERA_POSTER_QR=<text>.
The path wins when both are set; an unreadable path disables the injection rather than falling
back. With neither variable the library does nothing. The app needs no change and no SDK.
For an image poster AutoMobile supplies SIMCTL_CHILD_AM_CAMERA_POSTER_PATH. For a QR poster it supplies
SIMCTL_CHILD_AM_CAMERA_POSTER_QR with the text. The library renders the code on a white portrait
canvas with a quiet zone, whereas a host PNG is aspect-filled and loses its edges (the quiet zone)
to cropping. The ios/CameraPosterInjection/build.sh script also builds a fixture app for direct
validation.
The library swizzles the public AVFoundation surface:
AVCaptureDeviceandAVCaptureDeviceDiscoverySessionlist one back wide-angle video device; authorization reports authorized.AVCaptureDeviceInput,AVCaptureSession(add/remove inputs and outputs, start/stop, preset) accept the fake device and run a ~15 fps frame timer.AVCaptureVideoPreviewLayershows the poster as layer contents while the session runs.AVCaptureVideoDataOutputdelivers BGRA sample buffers of the poster.AVCaptureMetadataOutputdecodes the poster withCIDetectorand reports a QRAVMetadataMachineReadableCodeObjectabout every 500 ms.AVCapturePhotoOutputreturns anAVCapturePhotowhose data is the poster as PNG (1080x1440 portrait canvas, aspect-fill).UIImagePickerControllersource availability.
Fake objects are runtime subclasses made with class_createInstance (the real initializers are
unavailable without hardware). Their dealloc is a no-op, so they leak; objects are few.
Tool lifecycle¶
An injected IosCameraPosterRegistry stores image paths or QR text plus generated PNG paths
by simulator UDID, with an in-memory process-wide default. The startDevice tool records after selecting
or booting the simulator, including already-running simulators. It records only after the readiness
reservation’s ownership check, so a request rejected for another client’s simulator cannot
overwrite that client’s poster. The setDeviceState tool validates host
PNG/JPG/JPEG files and records or clears the poster. Whitespace is allowed; surface is echoed
and ignored. Both run the dylib provider’s ensure() before recording, so a missing compiler,
source or override fails the call that sets the poster and leaves the previous record intact;
clear never builds.
A record lasts until one of these happens:
- it is cleared;
- the simulator’s
killDevicecompletes (post-shutdown cleanup clears the UDID); - its session is released or unbinds it (a
setActiveDevicerebind). The session manager runsregisterIosCameraPosterSessionCleanup, plusSessionReleaseBroadcasterwith a device snapshot. Cleanup ignores upgrade-only re-announcements because the device may already belong to the next owner; - the daemon removes the device, or the daemon restarts.
A session that reuses the simulator therefore never inherits an earlier session’s poster.
setDeviceState returns supported: true, method: "ios_simulator_dyld_injection", the path
when set, and relaunchRequired: true. It never relaunches an app automatically. A running app
takes a new process environment only on relaunch. With a registered poster, launchApp
forces a cold launch and returns cameraPosterApplied: true; after clearing, use
launchApp coldBoot: true to remove injection from a running app. Existing DYLD entries and
prototype: true injection compose: both libraries remain in the colon-separated list and the
prototype port/token environment survives. Without a registered poster, launch is unchanged.
Like prototype: true, injection skips com.apple.* bundles, because SpringBoard and system apps
cannot take injection. The launch is unchanged and reports cameraPosterApplied: false rather than
failing, so system apps such as Settings stay launchable while a poster is set.
Physical iOS devices return a typed unsupported result from setDeviceState and an
ActionableError from startDevice; tvOS, watchOS and visionOS poster starts are refused.
The camera is injected into simulator app processes, not device hardware.
Dylib resolution¶
IosCameraPosterDylibProvider first checks AUTOMOBILE_IOS_CAMERA_POSTER_DYLIB. An explicit
missing path fails instead of falling back. Otherwise it locates the committed Objective-C source
relative to the module’s package/repository root or daemon launch directory, or uses
AUTOMOBILE_IOS_CAMERA_POSTER_SOURCE. Relative overrides resolve against the daemon launch
directory. The npm package ships ios/CameraPosterInjection/Injection/CameraPosterInjection.m
(package.json files, required by scripts/build/packed-runtime-assets.ts), so an installed
package finds it from <package>/dist/src/ by walking ancestors, with no override.
The source (about 30 KB) is built on demand rather than shipped as a prebuilt release asset;
AUTOMOBILE_IOS_CAMERA_POSTER_DYLIB serves users who supply their own build.
The source bytes’ SHA-256 determines
<AutoMobile data dir>/ios-camera-poster/<hash12>-sim-universal/libAMCameraPoster.dylib; the
flavor suffix keeps an older single-slice build from being reused. The provider reuses an existing
file. Otherwise an injected host command runner invokes xcrun --sdk iphonesimulator clang
with -arch arm64 -arch x86_64, ARC, simulator minimum 17.0 and the frameworks from build.sh,
then ad-hoc signs with codesign -f -s -. The universal binary lets Intel hosts and Rosetta-run
Node on Apple silicon both match the simulator, where process.arch alone could name the wrong
slice. Each build writes a uniquely named partial and renames it atomically
only after signing. SingleFlight coalesces concurrent builds within the default provider;
separate processes can build private partials safely. The build needs no clock, sleep or device commands.
Missing Xcode/xcrun errors explain installation and the prebuilt override. Missing source errors
name the expected packaged path and the overrides. Compile/sign errors include bounded, trimmed command
stderr. Preparation failures stop launchApp with an ActionableError before app launch;
a registered poster is never silently dropped. Invalid extensions and missing images are typed
state failures and leave the prior record intact.
Limits¶
- The built library targets arm64 and x86_64 iOS Simulator 17.0 and later.
- Takes effect only at launch; hardened or system apps that strip
DYLD_INSERT_LIBRARIESare out. - Process-wide swizzles; apps that subclass capture classes or use private camera paths may bypass it.
- Not implemented:
UIImagePickerControllerpresentation and capture,AVCaptureStillImageOutput, device formats, capture connection topology, camera controls, depth. Metadata geometry is synthetic. VisionKitDataScannerViewControllerreportsisSupported == falseon the simulator and is not changed.- Relies on private layer state initialisation of
AVCaptureVideoPreviewLayer; re-verify per Xcode.
Fallback¶
xcrun simctl addmedia plus putAppFile media_library cover photo-picker (PHPicker) flows. They do
not cover live preview, AVCapturePhotoOutput or QR scanning.