Skip to main content

GigE Virtual Camera

A native macOS application that creates virtual cameras from GigE Vision industrial cameras, making them available to any macOS application including HyperStudy experiments.

Overview​

The GigE Virtual Camera application bridges the gap between professional GigE Vision cameras and consumer applications. It creates a virtual camera device that appears as a standard webcam in any macOS application, allowing you to use high-quality industrial cameras in video conferencing, recording software, and HyperStudy experiments.

Features​

  • System Extension Architecture: Implements a proper CMIO System Extension for virtual camera functionality
  • Native macOS Integration: Appears as a standard camera in all macOS apps
  • Universal GigE Support: Works with any GigE Vision compliant camera via Aravis library
  • Real-time Preview: Built-in preview with camera status and controls
  • Professional Features: Designed for industrial and professional camera integration
  • Notarized & Signed: Properly signed with Developer ID for secure distribution

System Requirements​

  • Operating System: macOS 12.3 (Monterey) or later
  • Processor: ARM64 (Apple Silicon) Mac
  • Network: GigE Vision compliant camera on the same network
  • Permissions: System Extension approval (first launch only)

Installation​

Download the latest release:

Loading latest release info...

Step-by-Step Installation​

  1. Install the Application

    • Double-click the downloaded DMG file
    • Drag GigEVirtualCamera.app to your Applications folder
    • Eject the DMG

  2. First Launch

    • Open GigEVirtualCamera from your Applications folder
    • If you see a warning about an unidentified developer (rare with notarization), right-click and select "Open"

  3. Grant System Extension Permission

    When you first launch the app, macOS will display a notification:

    "System Extension Blocked" A program tried to load new system extension(s) signed by "Luke Chang"

    To approve:

    • Click the notification, or go to System Settings → Privacy & Security
    • Scroll to the Security section
    • Find the message about blocked system software from "Luke Chang"
    • Click "Allow"
    • Enter your administrator password if prompted
    • Restart the app after approving

  4. Grant Camera Permissions

    • Go to System Settings → Privacy & Security → Camera
    • Find GigEVirtualCamera in the list
    • Toggle it ON

  5. Verify Installation

    systemextensionsctl list

    You should see com.lukechang.GigEVirtualCamera.Extension listed.

Usage​

Connecting to a Camera​

  1. Launch GigEVirtualCamera
  2. Select Camera: Your GigE Vision cameras on the network appear in the dropdown menu
  3. Click Connect: The app establishes connection and starts streaming
  4. Verify Preview: The preview window shows the live camera feed

Using Test Camera​

For testing without physical hardware:

  1. Select "Test Camera (Aravis Simulator)" from the dropdown
  2. Click Connect
  3. A simulated feed will appear

Using in Other Applications​

The virtual camera appears as "GigE Virtual Camera" in all macOS applications:

HyperStudy Experiments:

  1. In HyperStudy's device setup, select camera source
  2. Choose "GigE Virtual Camera"
  3. Your GigE camera feed is now available to the experiment

Zoom / Microsoft Teams / Google Meet:

  1. Open video settings in your conferencing app
  2. Select "GigE Virtual Camera" as your camera
  3. Your GigE feed becomes your video source

QuickTime Player:

  1. File → New Movie Recording
  2. Click dropdown arrow next to record button
  3. Select "GigE Virtual Camera"

OBS Studio:

  1. Add a new Video Capture Device source
  2. Select "GigE Virtual Camera"

Network Requirements​

Camera Network Setup​

  1. Same Network: Camera must be on the same network as your Mac
  2. Wired Connection: Use Ethernet for best performance (required for GigE bandwidth)
  3. IP Configuration: Use DHCP or configure static IP on camera

Firewall Settings​

GigE Vision uses UDP port 3956. Ensure your firewall allows:

  • System Settings → Network → Firewall → Options
  • Add GigEVirtualCamera to allowed applications

Testing Camera Detection​

# Install Aravis tools
brew install aravis

# List detected cameras
arv-camera-test-0.8

Architecture​

┌─────────────────────────────────────────────────────────────────────────┐
│ GigE Camera (Network)                                                   │
└────────────┬────────────────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Aravis Library (C++)                                                    │
│ ├─ Camera Discovery                                                     │
│ ├─ Frame Acquisition                                                    │
│ └─ GigE Vision Protocol Handling                                        │
└────────────┬────────────────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AravisBridge (Objective-C++)                                            │
│ └─ C++ to Swift Bridge                                                  │
└────────────┬────────────────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Main App (GigECameraApp)                                                │
│ ├─ SwiftUI Interface                                                    │
│ ├─ Camera Management                                                    │
│ ├─ Preview Display                                                      │
│ └─ Frame Sender                                                         │
└────────────┬────────────────────────────────────────────────────────────┘
             │ (XPC / CMIO Sink)
             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ System Extension (GigEVirtualCameraExtension)                           │
│ ├─ CMIO Extension Provider                                              │
│ ├─ Virtual Camera Device                                                │
│ └─ Frame Stream Management                                              │
└────────────┬────────────────────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ macOS Camera System                                                     │
│ └─ Available to all apps (HyperStudy, Zoom, QuickTime, etc.)            │
└─────────────────────────────────────────────────────────────────────────┘

Key Technologies​

  • CMIO (Core Media I/O): macOS camera extension framework
  • System Extensions: Apple's modern privileged extension architecture
  • Aravis: Open-source GigE Vision camera library
  • SwiftUI: Native macOS user interface
  • XPC: Secure inter-process communication

Troubleshooting​

System Extension Issues​

Extension not loading:

# Check extension status
systemextensionsctl list

# View extension logs
log stream --predicate 'subsystem == "com.lukechang.GigEVirtualCamera"'

"System Extension Blocked" persists:

  1. Go to System Settings → Privacy & Security
  2. Scroll down to Security section
  3. Click "Allow" next to the blocked extension message
  4. Restart your Mac if the option doesn't appear

Camera Not Detected​

  1. Verify Physical Connection

    • Camera is powered on
    • Ethernet cable is connected
    • Camera and Mac are on same network

  2. Test with Aravis Tools

    brew install aravis
    arv-camera-test-0.8

  3. Check Network Configuration

    • Verify IP addresses are in same subnet
    • Try pinging the camera's IP address
    • Check firewall settings

Virtual Camera Not Appearing​

  1. Check Permissions

    • System Settings → Privacy & Security → Camera
    • Ensure GigEVirtualCamera is enabled

  2. Verify Extension is Active

    systemextensionsctl list
    system_profiler SPCameraDataType

  3. Restart the App

    • Quit GigEVirtualCamera completely
    • Relaunch from Applications

  4. Restart Your Mac

    • Sometimes required after first extension approval

Performance Issues​

Low frame rate:

  • Ensure Gigabit Ethernet connection
  • Connect camera directly to Mac (avoid switches if possible)
  • Check network utilization in Activity Monitor
  • Try lowering camera resolution

Dropped frames:

  • Use wired connection (not WiFi)
  • Close other bandwidth-intensive applications
  • Check camera's internal buffer settings

Development​

For developers who want to build from source:

Prerequisites​

  • macOS 12.3+ (Apple Silicon recommended)
  • Xcode 15.0+
  • Homebrew

Building​

# Clone the repository
git clone https://github.com/hyperstudyio/hyperstudy-gige.git
cd hyperstudy-gige

# Install dependencies
brew install aravis

# Open in Xcode
open GigEVirtualCamera.xcodeproj

# Build and run (Cmd+R)

For detailed build instructions including code signing for distribution, see BUILDING.md.

Resources​

Release Notes​

v1.1.24​

Released: 2026-06-08

What's Changed​

  • fix(stream): recover by re-discovery + device ID, not stale link-local IP

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.23...v1.1.24

v1.1.23​

Released: 2026-06-08

What's Changed​

  • fix(stream): auto re-establish GVSP stream on physical link drop

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.22...v1.1.23

v1.1.22​

Released: 2026-06-07

What's Changed​

  • fix(stream): tune GVSP socket buffer + receive-thread priority to stop freeze

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.21...v1.1.22

v1.1.21​

Released: 2026-06-02

What's Changed​

  • diag(stream): surface Aravis GVSP stats in export; drop inert stall-watchdog code

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.20...v1.1.21

v1.1.20​

Released: 2026-06-01

What's Changed​

  • fix(camera): release GigE stream before camera + guard concurrent connects

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.19...v1.1.20

v1.1.19​

Released: 2026-05-31

What's Changed​

  • fix(extension): advertise the format we actually deliver (720p, variable rate)

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.18...v1.1.19

v1.1.18​

Released: 2026-05-29

What's Changed​

  • fix(extension): send source frames with the buffer's own PTS as host time

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.17...v1.1.18

v1.1.17​

Released: 2026-05-29

What's Changed​

  • refactor: review follow-ups — drop redundant connect retry, dead StreamState write, dead accessors
  • fix(app): network changes don't touch the stream; control errors non-fatal
  • fix(app): continuous capture+push; drop handshake; single reconnect path
  • fix(app): delete stall watchdog + dead-sink recovery; keep PTS tripwire
  • fix(app): deterministic sink connect-poll; remove forceRediscovery
  • fix(extension): delete StreamState app-group handshake
  • docs(extension): document single-producer source timeline + clamp role
  • fix(extension): self-re-arming sink consume loop; drop error-budget teardown
  • docs: use unsigned compile as the build gate (signed build is CI/user-run)
  • docs: implementation plan for sink-streaming rebuild
  • docs: spec for sink-streaming rebuild to CMIO reference model

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.16...v1.1.17

v1.1.16​

Released: 2026-05-28

What's Changed​

  • fix(reliability): add targeted dead-sink recovery

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.15...v1.1.16

v1.1.15​

Released: 2026-05-28

What's Changed​

  • fix(reliability): defang stall recovery; track all pipeline disruptions

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.14...v1.1.15

v1.1.14​

Released: 2026-05-28

What's Changed​

  • fix(reliability): MRC camera reliability + diagnostics fidelity

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.13...v1.1.14

v1.1.13​

Released: 2026-05-27

What's Changed​

  • fix(diagnostics): stop per-frame log/IPC churn from sink drain

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.12...v1.1.13

v1.1.12​

Released: 2026-05-27

What's Changed​

  • feat(diagnostics): capture extension logs via shared app-group file

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.11...v1.1.12

v1.1.11​

Released: 2026-05-25

What's Changed​

  • fix(app): reliability pass — sink rediscovery, control clamps, observer leak
  • fix(extension): repair "one frame then freeze" failure mode

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.10...v1.1.11

v1.1.10​

Released: 2026-05-25

What's Changed​

  • fix(ui): suppress false stall banner when no consumer is attached

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.9...v1.1.10

v1.1.9​

Released: 2026-05-24

What's Changed​

  • fix(diagnostics): grant user-selected read-write so save dialog appears

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.8...v1.1.9

v1.1.8​

Released: 2026-05-24

What's Changed​

  • fix(ui): drop step: from exposure slider to avoid 99k-tick-mark freeze

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.7...v1.1.8

v1.1.7​

Released: 2026-05-23

What's Changed​

  • chore(build): use version-agnostic /opt/homebrew/opt/* symlinks for deps
  • fix(preview): cap NSImage retention with coalesced main-thread updates

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.6...v1.1.7

v1.1.6​

Released: 2026-05-23

What's Changed​

  • chore(logging): drop redundant per-second frame logs from AravisBridge

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.5...v1.1.6

v1.1.5​

Released: 2026-05-23

What's Changed​

  • fix(ui): diagnostics freeze + state-aware preview empty state

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.4...v1.1.5

v1.1.4​

Released: 2026-05-23

What's Changed​

  • review followups: extension Install CTA, ExtensionManager singleton, dead code, Unmanaged doc
  • Design + reliability pass: semantic colors, cancellable feedback, dead-code removal
  • fix(release): generate release body from git log instead of PR list

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.3...v1.1.4

v1.1.3​

Released: 2026-05-23

What's Changed​

  • fix(ui): pin window to fixed 960x680, drop 400px width clamp

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.2...v1.1.3

v1.1.2​

Released: 2026-05-23

What's Changed​

  • ui: two-column layout with always-on preview
  • fix(release): drop static boilerplate from generated release body

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.1...v1.1.2

v1.1.1​

Released: 2026-05-23

What's Changed​

  • Reliability fixes + diagnostics drawer
  • fix(release): grant actions:write so docs-sync dispatch isn't 403 (#6)

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.1.0...v1.1.1

v1.1.0​

Released: 2026-05-20

What's Changed​

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.0.16...v1.1.0

v1.0.16​

Released: 2026-05-02

What's Changed​

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.0.15...v1.0.16

v1.0.15​

Released: 2026-05-02

What's Changed​

New Contributors​

Full Changelog: https://github.com/hyperstudyio/hyperstudy-gige/compare/v1.0.14...v1.0.15

Release notes are automatically synced from GitHub releases.