Your Mac's camera, in the iOS Simulator. Free and open.
The iOS Simulator has never had a real camera. AVCaptureDevice returns
nil. Every app that touches the camera β QR scanners, barcode readers,
document capture, ML pipelines, AR prototypes, video calling β either
stubs the camera path, runs only on physical devices, or ships a brittle
"use a photo instead" fallback.
SimulatorCamera registers a virtual camera at the macOS system level
using Apple's CMIOExtension API. The iOS Simulator (Xcode 16+) sees the
virtual camera through standard AVFoundation. Your existing
AVCaptureSession code Just Works. Zero SDK integration. Zero
Info.plist changes. Zero #if targetEnvironment(simulator) branches.
- π₯ Mac webcam β iOS Simulator β your existing app sees frames at 30 FPS, 1280Γ720
- π¬ Video file source β drop in any MP4 / MOV / HEVC, loops cleanly
- πΌ Static image source β pick a PNG / JPG, becomes the camera feed
- π² QR code generator β programmatic QR for scanner testing
- π Test pattern β built-in colorbar / scrolling stripe, always available
- π€
simcamctlCLI βsimcamctl set-source --qr "TOKEN"for CI / AI agents - π‘ Zero SDK β your iOS app code does not import or link anything from this project
- π΅ Zero device required β runs entirely in the iOS Simulator
- π Free, MIT-licensed, open source β fork it, ship it, sell it, no fees
An ordinary scanner app in the iOS Simulator: AVCaptureDevice returns
"SimulatorCamera", the preview shows whatever source you pick, and the QR code
is decoded through AVCaptureMetadataOutput. The app imports nothing from this
project. Full-quality video.
1. Get the Mac app. Download the notarized SimulatorCamera-<version>.dmg
from Releases, drag the app to /Applications and open it.
Once the Homebrew tap is updated you can instead run:
brew install --cask dautovri/tap/simulatorcameraNo release published yet? Until the first notarized release is on the Releases page, the only option is building from source (below).
2. Click Activate, then approve in System Settings β General β Login Items &
Extensions. This is needed once per machine, and the app must live in
/Applications.
3. Load the injection library into your Simulator app β see iOS Simulator apps below. On Xcode 26/27 simulators this step is required; there is nothing else to import or change in your app's code.
Not a Swift Package. SimulatorCamera has no
Package.swiftand cannot be added via SPM, CocoaPods, or Carthage β on purpose. It is a macOS system extension (Apple'sCMIOExtensionAPI) plus a Simulator-side library, not something your app links.
Requires macOS 14+, Xcode 16+ and
XcodeGen (brew install xcodegen).
git clone https://github.com/dautovri/SimulatorCamera.git
cd SimulatorCamera- In
project.yml, changeSIMCAM_BUNDLE_PREFIXto a prefix you own (com.dautovis registered to another team) and set your signing team on the SimulatorCamera and SimulatorCameraExtension targets. xcodegen generate && open SimulatorCamera.xcodeproj, then build.- Move the built app to
/Applicationsand launch it.
Heads-up: macOS refuses to activate a system extension from a plain Apple Developmentβsigned build unless system extension developer mode is on (
systemextensionsctl developer on, which requires SIP to be disabled). A Developer IDβsigned, notarized build β whatscripts/build-release.shproduces β activates normally. See #6.
The iOS Simulator's own capture stack has no path to Mac cameras: in iOS 26.5
and iOS 27 simulators AVCaptureDevice lists nothing, not even the Mac's
built-in camera. SimulatorCamera therefore ships a small library that you load
into your app in the Simulator only. Your app still imports nothing.
- Run the SimulatorCamera Mac app and pick a source (or use
simcamctl feed --qr "TEXT"/--image PATH/--pattern/--camera). - In Xcode: Edit Scheme βΊ Run βΊ Arguments βΊ Environment Variables, add
DYLD_INSERT_LIBRARIES=/Applications/SimulatorCamera.app/Contents/Resources/libSimCamInject.dylib. From the command line:SIMCTL_CHILD_DYLD_INSERT_LIBRARIES=<that path> xcrun simctl launch booted <bundle id>. - Run on a Simulator.
AVCaptureDevice.default(for: .video)returns "SimulatorCamera"; frames reachAVCaptureVideoDataOutput,AVCaptureVideoPreviewLayer, QR codes reachAVCaptureMetadataOutput, andAVCapturePhotoOutputreturns JPEGs. Without the Mac app running you see a built-in test pattern.
Frames travel through /private/tmp/SimulatorCamera/frame.bin
(SimulatorInjection/SCFrameStore.h). Video frames are BGRA; apps that force a
420 YpCbCr format get BGRA anyway. Not supported yet: barcode types other than
QR, depth, multi-cam.
The injection library supports AVCaptureMovieFileOutput start/stop recording,
isRecording, recording delegates, and separate video/audio connections. It
writes finalized H.264 + mono AAC QuickTime movies from injected video frames
and the Simulator's microphone route. Apps keep using AVFoundation; there is no
app-side writer or library import. Video connection rotation and mirroring are
written into the movie's display transform.
Mac webcam images are already upright, unlike an iPhone's sensor-coordinate
buffers. Camera-tagged frames therefore use a 90Β° portrait reference: a
portrait connection requesting 90Β° displays the host image upright, while 0Β°,
180Β° and 270Β° still rotate relative to that reference. Mirroring is applied in
display coordinates. Webcam preview and movies use the same mapping, preserving
the source aspect ratio and actual frame dimensions without cropping/resampling
the recorded pixels. Other source types use the existing zero-offset sensor
coordinate convention. Rebuild simcamctl as well as the injection library:
feed --camera now writes the camera source tag needed for normalization.
Add a native microphone AVCaptureDeviceInput, obtain microphone permission,
and activate a recording-capable AVAudioSession. The library preserves the
caller's audio-session settings. Audio comes from an internal AVAudioEngine,
because the injected capture session does not run a native capture graph.
Adding AVCaptureAudioDataOutput to that session does not deliver audio.
Audio from a selected video file source is not forwarded.
The Simulator's host input must carry sound. A silent virtual/loopback input produces a genuinely silent recording; this library does not substitute a tone or pretend microphone permissions were granted. No system extension is needed for the built-in moving test pattern plus microphone recording.
Wait for didFinishRecording before reading the completed file or starting the
next take. Startup cancellation and missing samples fail with an error;
stopping a session or removing its output finalizes an already-started take.
The supported subset uses new local .mov destinations and fixed frame
dimensions. Custom codec/output settings, recording limits, pause/resume, and
full device-quality timing/latency guarantees are outside this implementation.
An injected session remains injected after input removal; use a new session to
return to native capture. This avoids committing fake configuration into the
Simulator's stub graph, which otherwise emits spurious runtime errors.
See recording verification for isolated public-API probes, decoded audio/video checks, and an unchanged-caller harness.
An optional host controller can provide a Unix socket via SIMCAM_BRIDGE_SOCKET
in the injected app's environment. On the first injected session's startRunning,
the library connects and sends CAPTURE\n. The controller starts its hardware
feeds and replies with one byte, R, only when live frames/audio are ready.
The connection remains open until the last session stops or is released; process
exit also closes it automatically. The controller must stop its feeds when the
last client disconnects. Failed startup leaves the session stopped. Controller
loss interrupts capture; managed capture never substitutes a test pattern.
simcamctl feed and Tests/HostAudioFeed accept SIMCAM_STOP_ON_STDIN_EOF=1
for supervised use: keep their stdin pipes open while owned, and close them to
stop. This also releases hardware when a controller crashes. A zero duration
keeps HostAudioFeed running until its owner stops it.
Open the SimulatorCamera Mac app:
| Source | Use case |
|---|---|
| Test Pattern | Default. Confirms wiring works. No permissions, no setup. |
| Mac Camera | Live webcam (built-in or external). First use prompts for camera access. |
| Video File | Pre-recorded scenarios. Loops at EOF. Honors orientation metadata. |
| Static Image | Pin a frame for visual UI tests. Same image, fresh timestamps. |
| QR Code | Programmatic QR for scanner / payment-flow tests. |
simcamctl is not bundled in the app or the release download. Build it
from source and put it on your $PATH:
xcodegen generate
xcodebuild -project SimulatorCamera.xcodeproj -scheme simcamctl -configuration Release build
# copy the built `simcamctl` (see BUILT_PRODUCTS_DIR) to /usr/local/bin
simcamctl ping
# extension reachable: "SimulatorCamera Virtual" source=test pattern streaming=yes
simcamctl set-source --qr "https://example.com/auth?token=ABC123"
# QR pushed (40 chars)
simcamctl set-source --image ./test-fixtures/receipt.png
# image pushed: receipt.png (1280x720)
simcamctl status
# active source: QR code
# connected clients: 1
# stream running: yes
# sink open: no
# last frame ts: 1714159823.412s
# frames received: 3
# frames rejected: 0Useful for:
- CI scripts that run
xcodebuild testagainst scanner / vision flows - AI agents that need to feed deterministic test fixtures into UI tests
- Manual QA scripts that walk through
simcamctl set-source --image fixture-N.png
Some popular libraries hard-code #if targetEnvironment(simulator) to
disable camera entirely. With SimulatorCamera the simulator does have a
camera, so those guards prevent the virtual feed from reaching your app.
We ship patch-package-compatible patches for known libraries:
| Library | Versions that may need patching | Patch |
|---|---|---|
expo-camera |
<55.0.11 |
patches/expo-camera/ |
react-native-vision-camera |
<5.0 |
patches/react-native-vision-camera/ |
react-native-webrtc |
all | patches/react-native-webrtc/ |
@fishjam-cloud/react-native-webrtc |
all | patches/fishjam-react-native-webrtc/ |
SimulatorCamera.app (container)
β CoreMediaIO sink stream (IOSurface frames) + custom properties
.app/Contents/Library/SystemExtensions/
com.dautov.SimulatorCamera.Extension.systemextension
β CMIOExtensionStream.send
macOS CoreMediaIO subsystem
β host AVFoundation
iOS Simulator process
β AVCaptureDevice.default(for: .video)
"SimulatorCamera Virtual" β your app
Full diagrams in docs/ARCHITECTURE.md.
Software Mansion shipped SimCam in
March 2026 β the same architecture as a polished commercial product
($19 lifetime). SimulatorCamera is the free, open-source alternative for
people who'd rather pay $0 and have the source. Both projects exist
because Apple has not (yet) shipped first-party simulator camera
support; both rely on Apple's public CMIOExtension API.
If you're after polished commercial support, buy SimCam β Software Mansion deserves it. If you'd rather contribute fixes back instead of opening tickets, you're in the right repo.
This is Act 1 of the iOS Simulator's missing sensor layer.
- v1.0 (now) β virtual camera, 5 sources, CLI, library patches
- v1.1 β IOSurface zero-copy frames (1080p/60fps), front/back camera switch, video pause/scrub
- v1.2 β scenario DSL:
simcamctl scenario play receipt-then-qr.jsonforxcodebuild testintegration - v2.0 β microphone passthrough (same architecture, different sensor)
- vN β BLE peripheral simulation, motion sensors, LiDAR β every sensor the iPhone has, simulated
See CONTRIBUTING.md. Good first issues are labelled on the tracker. For release mechanics, see RELEASING.md.
SimulatorCamera is fully MIT-licensed and maintained on donations. If it saves you a device-build loop, consider sponsoring or buying a coffee.
MIT β see LICENSE.
