Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ on:
jobs:
build-mac:
name: Build & notarize Mac app
runs-on: macos-14
runs-on: macos-15
timeout-minutes: 60

env:
Expand All @@ -25,8 +25,10 @@ jobs:
- name: Normalize VERSION (strip leading v)
run: echo "VERSION=${VERSION#v}" >> "$GITHUB_ENV"

- name: Select Xcode
run: sudo xcode-select -s /Applications/Xcode_15.4.app
- name: Select the current stable Xcode
uses: maxim-lobanov/setup-xcode@v1
with:
xcode-version: latest-stable

- name: Install xcpretty
run: gem install xcpretty --no-document
Expand Down Expand Up @@ -63,6 +65,13 @@ jobs:
name: mac-release-${{ env.VERSION }}
path: dist/*

- name: Print Homebrew cask checksum
run: |
SHA=$(shasum -a 256 "dist/SimulatorCamera-${VERSION}.dmg" | cut -d' ' -f1)
echo "### Cask values for v${VERSION}" >> "$GITHUB_STEP_SUMMARY"
echo "\`version \"${VERSION}\"\`" >> "$GITHUB_STEP_SUMMARY"
echo "\`sha256 \"${SHA}\"\`" >> "$GITHUB_STEP_SUMMARY"

- name: Create/Update GitHub Release
uses: softprops/action-gh-release@v2
if: startsWith(github.ref, 'refs/tags/')
Expand Down
78 changes: 36 additions & 42 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,60 +38,54 @@ virtual camera through standard `AVFoundation`. **Your existing

## Install

> **Status: pre-release. Build from source.** There is no published
> binary, no Homebrew cask, and no App Store listing yet. Distribution is
> still being decided — macOS system extensions have real constraints on
> how they can be shipped to the public. For now you build and sign it
> yourself with your own Apple developer account.

**1. Build the Mac companion app.**

Requires macOS 14+, Xcode 16+, and
[XcodeGen](https://github.com/yonaskolb/XcodeGen) (`brew install xcodegen`):
**1. Get the Mac app.** Download the notarized `SimulatorCamera-<version>.dmg`
from [Releases](../../releases), drag the app to `/Applications` and open it.
Once the Homebrew tap is updated you can instead run:

```bash
git clone https://github.com/dautovri/SimulatorCamera.git
cd SimulatorCamera
xcodegen generate
open SimulatorCamera.xcodeproj
brew install --cask dautovri/tap/simulatorcamera
```

In Xcode, set your own signing team on both the **SimulatorCamera** and
**SimulatorCameraExtension** targets, then build.

**2. Move the built app to `/Applications` and launch it.**
> **No release published yet?** Until the first notarized release is on the
> Releases page, the only option is building from source (below).

macOS refuses to activate a system extension from anywhere else — running
straight from Xcode's build directory will fail.
**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. Click Activate, then approve when System Settings prompts.**
**3. Load the injection library into your Simulator app** — see
[iOS Simulator apps](#ios-simulator-apps-xcode-2627) below. On Xcode 26/27
simulators this step is required; there is nothing else to import or change in
your app's code.

Approval lives in System Settings → General → Login Items & Extensions,
and is needed once per machine.
> **Not a Swift Package.** SimulatorCamera has no `Package.swift` and cannot be
> added via SPM, CocoaPods, or Carthage — on purpose. It is a macOS *system
> extension* (Apple's `CMIOExtension` API) plus a Simulator-side library, not
> something your app links.

That's it. No Xcode integration, no `Info.plist` changes, no `#if`
guards anywhere in your consuming app's code.
### Building from source

> **Not a Swift Package.** SimulatorCamera has no `Package.swift` and
> cannot be added via SPM, CocoaPods, or Carthage — on purpose. It's a
> macOS *system extension* (Apple's `CMIOExtension` API), not a library
> your app links. Install the Mac companion app with the `brew` command
> above; your iOS app imports and links **nothing** from this project.
Requires macOS 14+, Xcode 16+ and
[XcodeGen](https://github.com/yonaskolb/XcodeGen) (`brew install xcodegen`).

**3. Run any iOS Simulator app that uses the camera.** Open it in Xcode
16+, run on a Simulator, and `AVCaptureDevice.default(for: .video)`
returns "SimulatorCamera Virtual."

```swift
// This — yes, exactly this — works in the iOS Simulator now:
let session = AVCaptureSession()
let device = AVCaptureDevice.default(for: .video)!
let input = try AVCaptureDeviceInput(device: device)
session.addInput(input)
session.startRunning()
// frames flow through your existing AVCaptureVideoDataOutput delegates
```bash
git clone https://github.com/dautovri/SimulatorCamera.git
cd SimulatorCamera
```

1. In `project.yml`, change `SIMCAM_BUNDLE_PREFIX` to a prefix you own
(`com.dautov` is registered to another team) and set your signing team on
the **SimulatorCamera** and **SimulatorCameraExtension** targets.
2. `xcodegen generate && open SimulatorCamera.xcodeproj`, then build.
3. Move the built app to `/Applications` and 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 — what `scripts/build-release.sh`
> produces — activates normally. See
> [#6](https://github.com/dautovri/SimulatorCamera/issues/6).

## iOS Simulator apps (Xcode 26/27)

The iOS Simulator's own capture stack has no path to Mac cameras: in iOS 26.5
Expand Down
3 changes: 2 additions & 1 deletion RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,8 @@ There is no iOS Swift Package to release — the SDK was removed in v1.0.0.
a **draft** GitHub Release with the `.dmg`, `.zip`, and checksums.

5. **Update the Homebrew cask**
- Grab the DMG sha256 from `dist/SimulatorCamera-X.Y.Z.sha256` (or the
- Grab the DMG sha256 from the Release workflow's job summary (also in
`dist/SimulatorCamera-X.Y.Z.sha256` and the
Release page).
- Commit the updated `Casks/simulatorcamera.rb` to the tap repo
(`dautovri/homebrew-tap`):
Expand Down
18 changes: 10 additions & 8 deletions SimulatorCamera.xcodeproj/project.pbxproj
Original file line number Diff line number Diff line change
Expand Up @@ -464,6 +464,7 @@
MTL_FAST_MATH = YES;
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = macosx;
SIMCAM_BUNDLE_PREFIX = com.dautov;
SWIFT_COMPILATION_MODE = wholemodule;
SWIFT_OPTIMIZATION_LEVEL = "-O";
SWIFT_STRICT_CONCURRENCY = minimal;
Expand All @@ -482,7 +483,7 @@
"@executable_path/../Frameworks",
"@loader_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.SimulatorCamera.Tests;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera.Tests";
SDKROOT = macosx;
};
name = Debug;
Expand All @@ -502,7 +503,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.SimulatorCamera;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera";
PRODUCT_NAME = SimulatorCamera;
SDKROOT = macosx;
};
Expand All @@ -518,7 +519,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.simcamctl;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).simcamctl";
PRODUCT_NAME = simcamctl;
SDKROOT = macosx;
SKIP_INSTALL = NO;
Expand Down Expand Up @@ -590,6 +591,7 @@
ONLY_ACTIVE_ARCH = YES;
PRODUCT_NAME = "$(TARGET_NAME)";
SDKROOT = macosx;
SIMCAM_BUNDLE_PREFIX = com.dautov;
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
SWIFT_OPTIMIZATION_LEVEL = "-Onone";
SWIFT_STRICT_CONCURRENCY = minimal;
Expand All @@ -607,7 +609,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.simcamctl;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).simcamctl";
PRODUCT_NAME = simcamctl;
SDKROOT = macosx;
SKIP_INSTALL = NO;
Expand All @@ -625,7 +627,7 @@
"@executable_path/../Frameworks",
"@loader_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.SimulatorCamera.Tests;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera.Tests";
SDKROOT = macosx;
};
name = Release;
Expand All @@ -643,7 +645,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.SimulatorCamera.Extension;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera.Extension";
PRODUCT_NAME = "$(PRODUCT_BUNDLE_IDENTIFIER)";
SDKROOT = macosx;
SKIP_INSTALL = YES;
Expand All @@ -665,7 +667,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.SimulatorCamera;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera";
PRODUCT_NAME = SimulatorCamera;
SDKROOT = macosx;
};
Expand All @@ -684,7 +686,7 @@
"$(inherited)",
"@executable_path/../Frameworks",
);
PRODUCT_BUNDLE_IDENTIFIER = com.dautov.SimulatorCamera.Extension;
PRODUCT_BUNDLE_IDENTIFIER = "$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera.Extension";
PRODUCT_NAME = "$(PRODUCT_BUNDLE_IDENTIFIER)";
SDKROOT = macosx;
SKIP_INSTALL = YES;
Expand Down
5 changes: 4 additions & 1 deletion SimulatorCamera/ExtensionController.swift
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@ import Observation
import OSLog
import SystemExtensions

private let extensionBundleIdentifier = "com.dautov.SimulatorCamera.Extension"
/// The extension's bundle ID is the app's plus `.Extension` (see project.yml),
/// so a build re-signed under another prefix needs no source edit.
private let extensionBundleIdentifier =
(Bundle.main.bundleIdentifier ?? "com.dautov.SimulatorCamera") + ".Extension"

@Observable
@MainActor
Expand Down
2 changes: 1 addition & 1 deletion SimulatorCamera/SimulatorCamera.entitlements
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
<true/>
<key>com.apple.security.application-groups</key>
<array>
<string>$(TeamIdentifierPrefix)com.dautov.SimulatorCamera</string>
<string>$(TeamIdentifierPrefix)$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera</string>
</array>
<key>com.apple.security.device.camera</key>
<true/>
Expand Down
2 changes: 1 addition & 1 deletion SimulatorCameraExtension/Info.plist
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
<key>CMIOExtension</key>
<dict>
<key>CMIOExtensionMachServiceName</key>
<string>$(TeamIdentifierPrefix)com.dautov.SimulatorCamera.Extension</string>
<string>$(TeamIdentifierPrefix)$(PRODUCT_BUNDLE_IDENTIFIER)</string>
</dict>
<key>LSMinimumSystemVersion</key>
<string>$(MACOSX_DEPLOYMENT_TARGET)</string>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
<true/>
<key>com.apple.security.application-groups</key>
<array>
<string>$(TeamIdentifierPrefix)com.dautov.SimulatorCamera</string>
<string>$(TeamIdentifierPrefix)$(SIMCAM_BUNDLE_PREFIX).SimulatorCamera</string>
</array>
</dict>
</plist>
53 changes: 53 additions & 0 deletions docs/RELEASE_NOTES_v1.0.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# SimulatorCamera v1.0.0

Your Mac's camera, in the iOS Simulator. Free and open.

SimulatorCamera is a macOS companion app that feeds a virtual camera into the
iOS Simulator. Your app imports nothing and needs no `#if targetEnvironment(simulator)`
branches.

## Highlights

- **Virtual camera for the Simulator.** A Camera Extension registers
"SimulatorCamera Virtual" on the Mac; a small injected library
(`libSimCamInject.dylib`) brings it into Xcode 26 / 27 simulators, where
`AVCaptureDevice` otherwise lists no cameras at all. Video data output,
preview layers, QR metadata and photo capture are supported.
- **Five sources:** test pattern, Mac camera, video file, static image and a QR
code generator, all normalized to 1280x720 BGRA at 30 fps.
- **Movie recording with sound.** `AVCaptureMovieFileOutput` records H.264 + AAC
QuickTime files, with rotation and mirroring honored.
- **`simcamctl` for CI and agents.** `simcamctl feed --qr "TEXT" | --image PATH |
--pattern | --camera`, plus `status` and `ping`.
- **Reliable frame transport.** Frames now travel over CoreMediaIO sink streams
instead of a private XPC listener, which never worked end to end.

## Install

Download `SimulatorCamera-1.0.0.dmg`, drag the app to `/Applications` and open it.
The release is signed with a Developer ID and notarized; macOS only activates the
system extension for such builds (or for apps in `/Applications` with system
extension developer mode on). Click **Activate** and approve in System Settings →
General → Login Items & Extensions.

```bash
brew install --cask dautovri/tap/simulatorcamera # once the tap is updated
```

Then load the injection library into your Simulator app. In Xcode: *Edit Scheme ›
Run › Arguments › Environment Variables*, add `DYLD_INSERT_LIBRARIES` =
`/Applications/SimulatorCamera.app/Contents/Resources/libSimCamInject.dylib`.
See the [README](../README.md#ios-simulator-apps-xcode-2627).

## Requirements

macOS 14+, Apple silicon, Xcode 16+.

## Known limitations

- Barcode types other than QR, depth data and multi-cam are not supported.
- Frames are exchanged through `/private/tmp/SimulatorCamera/frame.bin`.
- Building from source needs your own Developer ID / notarization to activate the
extension on a Mac with SIP enabled (see [issue #6](https://github.com/dautovri/SimulatorCamera/issues/6)).

Full detail: [CHANGELOG.md](../CHANGELOG.md).
15 changes: 10 additions & 5 deletions project.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@ options:

settings:
base:
# Self-builders: change this one line (and set your signing team), then run
# `xcodegen generate`. Every bundle ID, the app group and the extension's
# Mach service name derive from it. (A command-line override does not work:
# Xcode resolves the embedded extension's file name without it.)
SIMCAM_BUNDLE_PREFIX: com.dautov
SWIFT_VERSION: "5.10"
MACOSX_DEPLOYMENT_TARGET: "14.0"
MARKETING_VERSION: "1.0.0"
Expand Down Expand Up @@ -56,7 +61,7 @@ targets:
NSSystemExtensionUsageDescription: SimulatorCamera installs a Camera Extension so the iOS Simulator can capture video without a physical device.
settings:
base:
PRODUCT_BUNDLE_IDENTIFIER: com.dautov.SimulatorCamera
PRODUCT_BUNDLE_IDENTIFIER: $(SIMCAM_BUNDLE_PREFIX).SimulatorCamera
PRODUCT_NAME: SimulatorCamera
CODE_SIGN_ENTITLEMENTS: SimulatorCamera/SimulatorCamera.entitlements
CODE_SIGN_STYLE: Automatic
Expand Down Expand Up @@ -110,10 +115,10 @@ targets:
# Reference: Apple's Camera Extension Xcode template TemplateInfo.plist
# only declares CMIOExtension + NSSystemExtensionUsageDescription.
CMIOExtension:
CMIOExtensionMachServiceName: $(TeamIdentifierPrefix)com.dautov.SimulatorCamera.Extension
CMIOExtensionMachServiceName: $(TeamIdentifierPrefix)$(PRODUCT_BUNDLE_IDENTIFIER)
settings:
base:
PRODUCT_BUNDLE_IDENTIFIER: com.dautov.SimulatorCamera.Extension
PRODUCT_BUNDLE_IDENTIFIER: $(SIMCAM_BUNDLE_PREFIX).SimulatorCamera.Extension
# sysextd requires the bundle file name to equal the bundle identifier
PRODUCT_NAME: $(PRODUCT_BUNDLE_IDENTIFIER)
CODE_SIGN_ENTITLEMENTS: SimulatorCameraExtension/SimulatorCameraExtension.entitlements
Expand All @@ -130,7 +135,7 @@ targets:
- path: Shared
settings:
base:
PRODUCT_BUNDLE_IDENTIFIER: com.dautov.simcamctl
PRODUCT_BUNDLE_IDENTIFIER: $(SIMCAM_BUNDLE_PREFIX).simcamctl
PRODUCT_NAME: simcamctl
CODE_SIGN_STYLE: Automatic
ENABLE_HARDENED_RUNTIME: YES
Expand All @@ -147,7 +152,7 @@ targets:
- path: Shared
settings:
base:
PRODUCT_BUNDLE_IDENTIFIER: com.dautov.SimulatorCamera.Tests
PRODUCT_BUNDLE_IDENTIFIER: $(SIMCAM_BUNDLE_PREFIX).SimulatorCamera.Tests
CODE_SIGN_STYLE: Automatic

schemes:
Expand Down
3 changes: 2 additions & 1 deletion scripts/build-release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,8 @@ fi

echo "▶︎ Verifying signature chain"

EXTENSION_BUNDLE="$APP_BUNDLE/Contents/Library/SystemExtensions/com.dautov.SimulatorCamera.Extension.systemextension"
APP_BUNDLE_ID="$(/usr/libexec/PlistBuddy -c 'Print CFBundleIdentifier' "$APP_BUNDLE/Contents/Info.plist")"
EXTENSION_BUNDLE="$APP_BUNDLE/Contents/Library/SystemExtensions/$APP_BUNDLE_ID.Extension.systemextension"
if [[ ! -d "$EXTENSION_BUNDLE" ]]; then
echo "ERROR: bundled extension not found at $EXTENSION_BUNDLE" >&2
exit 1
Expand Down
Loading