MacOS WebCam Controller

Direct USB UVC Hardware Control from the macOS Menu Bar & CLI (webcamctl) — Zero Virtual Cameras · 0% Video CPU Overhead

brew install --cask SilverFeit/tap/macos-webcam-controller

Install via Homebrew · Download .dmg · CLI (webcamctl) · Features · Architecture · User Guide · Español

---

Overview

MacOS WebCam Controller is a lightweight native macOS Menu Bar app + CLI (Swift + SwiftUI + C / IOKit) that unlocks physical sensor and ISP hardware registers on external USB webcams compliant with the UVC (USB Video Class) standard.

On Windows, operating system APIs (DirectShow / IAMCameraControl) expose every USB webcam's hardware control panel out of the box. On macOS, AVFoundation captures video frames from external USB cameras while ignoring their UVC control descriptors (isExposureModeSupported(.custom) returns false, and uvcassistantextension hides UVC control entities). As a result, most Mac tools resort to heavy virtual cameras that apply software filters on top of an already overexposed, motion-blurred, or color-shifted image.

MacOS WebCam Controller takes the pure hardware path: it communicates directly with your webcam's internal sensor and Image Signal Processor (ISP) over USB Endpoint 0 via IOKit (IOUSBLib) in real time — while Zoom, OBS Studio, Microsoft Teams, Google Meet, Webex, WhatsApp, FaceTime, or Chrome continue consuming the native camera feed with zero virtual cameras, zero Camera/Microphone TCC permissions, zero video latency, and 0% video re-encoding CPU/GPU drain.

🇪🇸 Español — Resumen del Proyecto (Haz clic para desplegar)

MacOS WebCam Controller es una aplicación nativa para la barra de menús de macOS + herramienta CLI (webcamctl) diseñada para modificar físicamente los registros internos del sensor y del procesador de imagen (ISP) de cualquier cámara web externa USB compatible con UVC (USB Video Class).

• Instalación Directa por Homebrew (brew): Instala tanto WebCam Controller.app como el comando de terminal webcamctl con brew install --cask SilverFeit/tap/macos-webcam-controller y actualiza con brew upgrade --cask macos-webcam-controller.
• 100% Hardware Real (Sin Cámaras Virtuales ni Permisos): En Zoom, Meet, Teams, OBS, WhatsApp o FaceTime sigues eligiendo el nombre real de tu cámara USB. La app inyecta paquetes UVC (SET_CUR, GET_CUR, GET_DEF) por Endpoint 0 mediante IOKit sin pedir permisos de Cámara/Micrófono y con 0% de carga de recodificación de video.
• Control Total + Obturación Fotográfica (1/60s): Exposición manual, velocidad de obturación en formato fotográfico (1/60s, 1/50s), ganancia/ISO, temperatura en Kelvin, brillo, contraste, matiz, saturación, nitidez, gamma, filtro anti-parpadeo (50 Hz / 60 Hz) con protección contra bloqueos UVC < 1.5, contraluz, enfoque y PTZ (1.3× Zoom, Pan, Tilt).
• Resoluciones (2K / 4K / 1080p), FPS Validados y Auto-Fix de Llamadas a 5 fps: Valida combinaciones reales (Formato, Resolución, FPS) desde los descriptores USB y mejora automáticamente llamadas lentas (<= 10 fps, como WhatsApp) a 1080p @ 30 fps.
• HUD Flotante, WebSocket en Red (ws://), CLI webcamctl y Menú Contextual: Incluye servidor WebSocket (ws://127.0.0.1:8765 o LAN 0.0.0.0) para controlar la cámara por red, menú contextual al hacer doble clic o clic derecho en el icono de la barra de menús (Turn Configuration Off/On, Open Advanced…, About, Quit), pad 2D PTZ interactivo, perfiles XU de fabricante (Insta360 Link, Anker C200/C310), HUD flotante opcional durante llamadas, control total por terminal (webcamctl set shutter=1/60 kelvin=4500, webcamctl look "warmer", webcamctl ws on) y barra inferior con la versión actual (v1.2.0 · GitHub ↗) y licencia MIT.

---

Why Direct Hardware Beats Virtual Cameras

Capability	MacOS WebCam Controller (Direct USB UVC)	Virtual Camera Software (CMIOExtension)
Where adjustments happen	Inside the camera's physical CMOS sensor & ISP chip before frames enter the USB cable	Post-processed in software after frames are already compressed & clipped
Motion blur & blown highlights	True electronic shutter control (1/60s, 1/125s) eliminates motion blur optically	Cannot recover clipped highlights or remove sensor motion blur
CPU / GPU / Battery impact	~0.0% — zero video frames decoded, filtered, or re-encoded	Continuous CPU/GPU frame copying & shader rendering during calls
Added video latency	0 ms	1–3 frames of pipeline buffering
Device selected in Zoom / OBS / Meet	Your real USB webcam directly	A synthetic "Virtual Camera" wrapper (often blocked in proctoring/enterprise apps)
macOS Permissions & System Extensions	None required (zero Camera, zero Mic, zero System Extension)	Requires Camera TCC permission + System Extension approval
CLI & Script Automation	Bundled webcamctl CLI (--json, Raycast/Shortcuts/Stream Deck ready)	GUI-only

---

Key Features

1. Instant Menu Bar Control + Standalone Settings Panel + Bottom GitHub Version Bar

• Left-click the webcam icon in the macOS Menu Bar to adjust primary exposure, photographic shutter (1/60s), color, and white-balance sliders on the fly during a call.
• Right-click the Menu Bar icon (or click Advanced… / Panel) to open the full Webcam Settings Panel (Basic, Advanced, and Preferences tabs), with optional Pin on Top so it floats above OBS, Zoom, or Photo Booth.
• Live Version & Update Badge at the Bottom: Both the Menu Bar popover and Settings Panel display your installed version (v1.2.0 · GitHub ↗) at the bottom. When a newer release is published on GitHub, the badge highlights as ⬆ Update vX.Y.Z · GitHub ↗ for one-click access to the latest release.

2. Full Sensor, ISP & Optical Control (Basic & Advanced)

• Exposure & Photographic Shutter (1/60s): Switch between hardware-supported Manual, Auto, Shutter Priority, and Aperture Priority modes; dial in exact physical Exposure Time displayed in standard shutter fractions (1/60s, 1/50s, 1/30s) and sensor Gain.
• Color & Tone ISP Pipeline: Hardware Brightness, Contrast, Hue, Saturation, Sharpness, and Gamma.
• Precision White Balance: Toggle Auto off to lock exact color temperature in Kelvin (e.g. 3200K tungsten to 6500K daylight).
• Lighting & Optics: Power Line Frequency (Disabled, 50 Hz, 60 Hz, Auto — with automatic Endpoint 0 stall protection on UVC < 1.5 cameras), Backlight Compensation (switch + multi-level fine slider), Low Light Compensation (AE Priority), Focus (Auto + manual optical focus), Optical/Digital Zoom (1.3×), Pan, Tilt, Aperture, Roll, Hardware Privacy Shutter, and Progressive Scan.

3. Hardware Resolutions, Validated FPS Matrix & Automatic 5 fps Call Fix

• Reads raw SC_VIDEOSTREAMING (0x02) USB descriptors (MJPEG, Uncompressed YUY2, H.264) to list every real hardware resolution (4K UHD, 2K QHD 2560×1440, 1080p FHD, UXGA, 720p HD, VGA) and enables only frame rates physically supported at that resolution.
• Automatic Slow-Mode (5 fps) Call Upgrade: Apps like WhatsApp Desktop often pick a webcam's highest uncompressed resolution at a choppy 5 fps. When enabled in Preferences, MacOS WebCam Controller detects <= 10 fps live streams within 2 seconds of call start and automatically negotiates smooth 1080p @ 30 fps MJPEG.

4. Zero-Permission Call Detection & Floating Stream Stats HUD

• Passively monitors CoreMediaIO (kCMIODevicePropertyDeviceIsRunningSomewhere) and CoreAudio active client processes to show which app is using your webcam (Zoom, FaceTime, Teams, OBS, WhatsApp, Chrome), live resolution/FPS, and call duration — without ever requesting Camera or Microphone permissions.
• Optional draggable, non-activating Floating Stream Stats HUD (Off / While in Call / Always) keeps live stream telemetry visible on screen without stealing window focus.

5. Punctual Single-Setting Rollback (↺), Hardware ID Presets & Anti-Reset Lock

• Every manual slider, mode selector, and stream parameter features a dedicated Rollback (↺) icon between the control icon and its value readout to restore only that register to factory GET_DEF.
• Bind by Hardware ID (VendorID:ProductID:Serial), save unlimited named presets with ★ Load at Start, and enable the Anti-Reset Hardware Lock (🔒) daemon to re-inject drifted registers every 2.5s.

---

Installation

Option A — Homebrew (Recommended)

Installs both /Applications/WebCam Controller.app and /opt/homebrew/bin/webcamctl (and clears Gatekeeper quarantine automatically):

brew install --cask SilverFeit/tap/macos-webcam-controller

To update to the latest version at any time:

brew upgrade --cask macos-webcam-controller

Option B — Download Prebuilt .dmg / .zip

1. Go to GitHub Releases (latest).
2. Download MacOS-WebCam-Controller-1.2.0.dmg (or MacOS-WebCam-Controller-1.2.0.app.zip).
3. Open the .dmg, drag WebCam Controller into Applications, and launch it.

Note

First Launch via Manual Download (Gatekeeper): Because open-source builds use ad-hoc signing rather than a paid Developer ID certificate, if you install manually via .dmg/.zip instead of Homebrew, right-click WebCam Controller.app → Open → Open (or run xattr -dr com.apple.quarantine "/Applications/WebCam Controller.app"). To add webcamctl to your PATH on manual installs:

ln -sf "/Applications/WebCam Controller.app/Contents/MacOS/webcamctl" /opt/homebrew/bin/webcamctl

Option C — Build from Source

Requires macOS 14+ on Apple Silicon with Xcode or Xcode Command Line Tools (swift 6.0+):

git clone https://github.com/SilverFeit/MacOS-WebCam-Controller.git
cd MacOS-WebCam-Controller

# Run unit + live USB UVC hardware test suite
swift run UVCCoreTests

# Build Release .app + webcamctl + .dmg + .app.zip + SHA256SUMS.txt
./Scripts/package_release.sh

---

Command-Line Interface (webcamctl)

webcamctl shares presets and lock state with the Menu Bar app and syncs live register changes immediately to the open UI. Every subcommand also supports --camera <id|index|name> and --json:

# List connected USB UVC cameras, firmware & active stream state
webcamctl list

# Inspect UVC units, Extension Unit GUIDs, control ranges & video modes (add --raw for USB hex dump)
webcamctl describe
webcamctl describe --raw

# Read all controls or specific aliases
webcamctl get
webcamctl get shutter kelvin brightness zoom stream

# Set physical hardware registers (supports 1/60s shutter fractions & relative +/- deltas)
webcamctl set shutter=1/60 gain=40 kelvin=4500 brightness=+5 anti_flicker=60hz

# Negotiate hardware resolution, frame rate & codec
webcamctl stream 2k 30 mjpeg
webcamctl stream 1080p 60

# Reset individual controls or all registers to factory GET_DEF
webcamctl reset brightness kelvin
webcamctl reset all

# Manage per-camera presets & Anti-Reset Hardware Lock
webcamctl preset list
webcamctl preset save "Studio Daylight" --load-at-start
webcamctl preset apply "Studio Daylight"
webcamctl lock on
webcamctl preset export ~/webcam-presets.json
webcamctl preset import ~/webcam-presets.json

# Turn your whole saved configuration off (factory defaults) or back on (re-applies your values)
webcamctl config off
webcamctl config on

# Natural-language / keyword look adjustment & scoped resets
webcamctl look "warmer, more contrast"
webcamctl reset-view
webcamctl reset-image

# Control or inspect the built-in WebSocket remote network control server (ws://)
webcamctl ws on
webcamctl ws lan on
webcamctl ws status

# Paste-ready Markdown report of your camera for a GitHub issue
webcamctl report

# Zero-permission active call inspection & GitHub update check
webcamctl who
webcamctl sessions
webcamctl check-update

---

Menu Bar Menu, URL Scheme & Global Shortcuts

Right-click or double-click the menu bar icon for a context menu:

1. Turn Configuration Off / On — off parks your saved values and returns the camera to its factory defaults (the Anti-Reset Lock and startup presets stand down); on re-applies them.
2. Open Advanced…
3. About WebCam Controller — version, license and GitHub links.
4. Quit WebCam Controller

The Advanced tab ends with the project license line: Released under the MIT License. Copyright © 2026 SilverFeit.

webcamcontroller:// URL scheme

Shortcuts ("Open URL"), Raycast, Stream Deck and the Terminal can drive the app without opening any window:

URL	Action
webcamcontroller://preset/Meeting	Apply a saved preset by name, by number (preset/2) or preset/default
webcamcontroller://config/off · on · toggle	Turn your saved configuration off / on
webcamcontroller://lock/on · off	Anti-Reset Hardware Lock
webcamcontroller://reset	Restore factory defaults (GET_DEF)
webcamcontroller://camera/Brio	Select a camera by index, ID, serial or name
webcamcontroller://set?brightness=+8&shutter=1/60	Write controls (same tokens as webcamctl set)

Add ?camera=Name to any link to choose the camera first.

open -g "webcamcontroller://preset/Meeting"

Global shortcuts (optional, no permissions)

Enable Global shortcuts in Preferences: ⌃⌥⌘0 turns your configuration on/off and ⌃⌥⌘1–⌃⌥⌘5 apply presets 1–5, from any app.

Network WebSocket Remote Control (ws://host:port)

Enable WebSocket Server for Remote Camera Control in Preferences (or from the quick card in Advanced) to control your USB webcam over ws://127.0.0.1:8765 or across your local network (Allow LAN access 0.0.0.0 → ws://<LAN-IP>:8765) with optional token authentication. Connected clients receive live state_changed JSON broadcasts and can send either JSON actions or plain-text CLI commands:

{"action": "set", "controls": {"brightness": 12, "white_balance": 4500, "zoom": 140}}
{"action": "stream", "spec": "2560x1440@30"}
{"action": "preset", "name": "Studio Daylight"}
{"action": "config", "state": "toggle"}
{"action": "look", "phrase": "warmer, more contrast"}

Camera report, 2D PTZ pad, vendor XU profiles, presets export/import & USB link check

• Interactive 2D PTZ Framing Pad (Advanced): Drag the 16:9 viewport box to pan and tilt simultaneously over USB Endpoint 0, or double-click to reset view (Zoom, Pan, Tilt).
• Vendor Extension Unit (XU) Profiles: Built-in support for Insta360 Link series, Anker PowerConf C200, and AnkerWork C310 vendor controls (HDR, Field of View 65°/78°/95°, EV compensation, Face Auto-Focus/Exposure, AI Mic Noise Reduction) plus user JSON profiles in ~/Library/Application Support/WebCamController/Profiles/.
• Preferences → Copy Camera Report (or webcamctl report) copies your camera's identity, descriptor units, supported controls and video modes and opens a GitHub issue to paste it into.
• Preferences → Presets: Export… / Import… move presets between Macs as JSON.
• A USB 3 camera linked at USB 2 speed shows a warning in the panel, since a USB 2 port, hub or cable caps resolution and frame rate.
• Double-click a slider's label to reset it to the camera default.
• All Endpoint 0 control transfers are serialized and rate-limited, and known firmware / USB-mode-switch extension selectors can never be written.

How Direct USB Hardware Control Works

USB Video Class (UVC) cameras split communication into two independent logical interfaces inside the same physical USB cable:

1. Video Streaming Interface (bInterfaceSubClass = 0x02): High-bandwidth pipe owned by macOS UVCAssistant / AVFoundation, delivering untouched video frames straight to Zoom, OBS, Teams, or your browser.
2. Video Control Interface (bInterfaceSubClass = 0x01 — Endpoint 0): Lightweight control channel where MacOS WebCam Controller and webcamctl send non-exclusive IOUSBInterfaceInterface / IOUSBDeviceInterface control transfers (GET_INFO, GET_MIN, GET_MAX, GET_RES, GET_DEF, GET_CUR, SET_CUR) directly to the Camera Terminal (CT) and Processing Unit (PU).

---

Requirements & Compatibility

• Mac Architecture: Apple Silicon (arm64 — M1, M2, M3, M4, and newer).
• Operating System: macOS 14.0 Sonoma or later (tested through macOS 27.0.1).
• Supported Cameras: External UVC-compliant USB webcams (Logitech, Elgato, Creative, Razer, Insta360, Anker, Obsbot, Sony/Canon/Lumix UVC interfaces, and generic USB 2.0/3.0 UVC webcams).
• Not Supported: Built-in MacBook / iMac FaceTime HD cameras (connected to Apple's proprietary internal ISP rather than USB UVC).

---

Privacy & Security by Design

• Zero Camera Permission: Never opens an AVCaptureSession and never reads a single pixel of your video feed.
• Zero Microphone Permission: Passive call attribution inspects only macOS CoreMediaIO / CoreAudio process metadata — never audio samples.
• Zero Telemetry: Presets and call history stay 100% local in UserDefaults (com.webcamcontroller.uvc) and bounded local logs (~/Library/Logs/WebCamController.log). The only network request is a lightweight GitHub Releases version check (api.github.com/repos/SilverFeit/MacOS-WebCam-Controller/releases/latest), which can be toggled off anytime in Preferences.
• Zero Kernel / System Extensions: Pure user-space IOKit USB control transfers.

Read the Full User Guide (docs/USER_GUIDE.md) and Changelog (CHANGELOG.md) for complete details.

---

Project Structure

MacOS-WebCam-Controller/
├── Package.swift                        # SwiftPM manifest (CUVCHardware + UVCCore + App + webcamctl + Tests)
├── VERSION                              # Single source of truth for release & bundle version
├── Casks/macos-webcam-controller.rb     # Homebrew Cask definition (synced with SilverFeit/homebrew-tap)
├── Sources/
│   ├── CUVCHardware/                    # C11 IOKit / IOUSBLib UVC Endpoint 0, XU & raw descriptor engine
│   ├── UVCCore/                         # Swift 6 device introspection, CLI bridge, call monitor & updater
│   ├── WebcamControllerApp/             # Native AppKit NSStatusItem + SwiftUI Menu Bar, Panel & Stream HUD
│   └── webcamctl/                       # Command-line interface for scripting, Raycast, Shortcuts & CI
├── Tests/UVCCoreTests/                  # Unit + live USB hardware register read/write verification suite
├── Scripts/                             # App + CLI bundle builder, Retina .icns generator & DMG packager
└── docs/                                # User Guide, Retina UI screenshots & vector USB architecture diagram

---

License

Released under the MIT License. Copyright © 2026 SilverFeit.

---

Topics & Hashtags

#macOS #WebcamController #Homebrew #CLI #UVC #USBCamera #WebcamSettings #MenuBarApp #AppleSilicon #SwiftUI #IOKit #HardwareControl #ManualExposure #WhiteBalance #OBSStudio #Zoom #VideoConferencing #StreamingTools #MacUtilities #OpenSource