Webcam Mirror Preview
Relevant source files
The following files were used as context for generating this wiki page:
The Webcam Mirror Preview is a utility feature within Buddi that provides a quick camera mirror directly from the macOS notch. It allows users to toggle a live video feed from integrated or external cameras, serving as a convenient tool for checking one's appearance or surroundings during work sessions.
The system is built upon the AVFoundation framework, utilizing a centralized manager to handle device discovery, authorization, and capture session lifecycle. The preview is rendered within the notch UI using a custom SwiftUI view that wraps a native AVCaptureVideoPreviewLayer.
Sources: README.md:37, buddi/managers/WebcamManager.swift:10-15
Architecture and Camera Management
The feature follows a singleton-based management pattern. The WebcamManager acts as the central authority for all camera-related operations, including checking hardware availability and managing the AVCaptureSession.
WebcamManager Core Logic
WebcamManager handles the complex asynchronous nature of camera hardware. It maintains a dedicated serial queue, sessionQueue, to perform session configurations off the main thread to prevent UI blocking.
Key Components
| Component | Responsibility |
|---|---|
WebcamManager | Manages AVCaptureSession, hardware discovery, and authorization states. |
CameraPreviewView | SwiftUI view that handles user interaction and conditional rendering based on session state. |
CameraPreviewLayerView | An NSViewRepresentable that bridges the AVCaptureVideoPreviewLayer into SwiftUI. |
BuddiViewModel | Coordinates the expanded state of the camera within the notch UI. |
Sources: buddi/managers/WebcamManager.swift:10, buddi/components/Webcam/WebcamView.swift:12-90, buddi/models/BuddiViewModel.swift:65
Lifecycle and Session Flow
The capture session lifecycle is tightly coupled with UI events. When the CameraPreviewView appears or is tapped, the manager attempts to start the session; when the view disappears, the session is stopped and resources are cleaned up to conserve power.
Session Initialization Sequence
The following sequence diagram illustrates the communication between the UI and the hardware manager:
Technical Implementation Details
Mirroring and Clipping
To provide a natural "mirror" experience, the CameraPreviewView applies a horizontal scale effect of -1. The view also dynamically adjusts its clipping shape based on user preferences for notch aesthetics (rectangle vs. rounded).
Sources: buddi/components/Webcam/WebcamView.swift:23-28
Hardware Event Monitoring
The WebcamManager observes AVCaptureDeviceWasDisconnected and AVCaptureDeviceWasConnected notifications. This ensures the UI updates immediately if an external webcam is plugged in or removed.
Sources: buddi/managers/WebcamManager.swift:60-65, buddi/managers/WebcamManager.swift:186-203
Error Handling
The system categorizes errors into three primary states:
- deviceUnavailable: No physical camera found.
- accessDenied: User refused privacy permissions.
- configurationFailed: Errors during
AVCaptureSessionsetup.
Sources: buddi/managers/WebcamManager.swift:42-55
Code Snippet: Session Configuration
// buddi/managers/WebcamManager.swift:130-145
session.beginConfiguration()
session.sessionPreset = .high
session.addInput(videoInput)
let videoOutput = AVCaptureVideoDataOutput()
videoOutput.setSampleBufferDelegate(nil, queue: nil)
if session.canAddOutput(videoOutput) {
session.addOutput(videoOutput)
}
session.commitConfiguration()
Sources: buddi/managers/WebcamManager.swift:130-145
Integration with Notch UI
The webcam feature is integrated into the BuddiViewModel, which manages the isCameraExpanded state. This state determines the size and visibility of the camera module when the user interacts with the notch. The buddiApp.swift also manages hotkeys that can trigger notch states, although camera specific toggles are primarily handled via taps on the preview area.
Sources: buddi/models/BuddiViewModel.swift:47-49, buddi/buddiApp.swift:515-555
The Webcam Mirror Preview provides a lightweight, high-performance video preview solution. By leveraging AVCaptureVideoPreviewLayer and a dedicated background queue for session management, it ensures that the Buddi notch remains responsive while providing real-time camera access.