Screen Capture and Recording Capabilities in Vorssaint Utils: A Technical Deep Dive

The Vorssaint Utils screen capture and recording feature provides a modular, scriptable video recorder that supports full-screen, window, or regional capture with system audio and microphone mixing, real-time overlays, non-destructive editing, and MP4/MOV export through a service-oriented Swift architecture.

The screen capture and recording subsystem in Vorssaint Utils implements a production-ready media pipeline for macOS applications. Built around a clean separation between capture logic, composition engines, and UI layers, this feature allows developers to programmatically control recording sessions or integrate customizable editing interfaces directly into their apps.

Core Recording Engine and Session Management

ScreenRecorderService Orchestration

At the heart of the screen capture and recording capability lies ScreenRecorderService, a singleton service that orchestrates the entire capture pipeline. Located in Sources/Vorssaint/Services/Recorder/ScreenRecorderService.swift, this class creates and manages an AVCaptureSession that can target the full display, a selected window, or a user-defined region.

The service exposes a simple toggle interface for programmatic control:

import Vorssaint

// Toggle recording – starts if idle, stops if already recording
ScreenRecorderService.shared.toggle()

ScreenRecorderService monitors recording permissions through the AppFeature.screenRecorder flag and integrates with the radial menu system via RadialMenuTool.screenRecorder to update UI state in real time.

Permission Handling and Availability Checks

The feature respects macOS security boundaries by checking screenRecorder permissions before initializing capture hardware. The system stores availability status using migrationDefaults.set(true, forKey: AppFeature.screenRecorder.availabilityKey) and dynamically responds to permission changes through AppFeature.screenRecorder.monitorsPermissionChanges.

Media Processing and Quality Configuration

Frame Rate Sanitization and Bitrate Control

RecorderComposer.swift handles the assembly of raw video frames into composited output. It applies frame-rate sanitization through RecorderSupport.sanitizedFrameRate to ensure compatibility with target devices, then calculates optimal encoding parameters.

The composer determines visual fidelity using:

• RecorderSupport.sanitizedQuality – Validates user-selected quality presets against hardware capabilities
• RecorderSupport.averageBitRate – Computes target bitrate based on resolution and frame rate constraints
• RecorderSupport.outputSize – Calculates final video dimensions while respecting aspect ratio locks

Output Size Calculation

These calculations ensure the screen capture and recording feature produces files optimized for streaming or archival without requiring post-processing re-encoding.

Export Pipeline and File Formats

Staging and Finalization Workflow

RecorderExporter.swift manages the transition from raw capture to finished media file. The exporter writes to MP4 or MOV containers using a two-phase staging system:

1. Staging Phase – Raw frames write to a temporary location returned by RecorderSupport.stagingURL
2. Commit Phase – RecorderSupport.commitExport atomically moves finalized data to the destination path

This approach prevents corruption of existing files if recording interrupts unexpectedly.

Take Store Management

The RecorderTakeStore class maintains a reference to all raw capture directories ("takes") and provides APIs for importing and exporting recorded sessions. Access the current take via RecorderTakeStore.shared.currentTake before initiating export operations.

Overlay System and Video Editing

Image and Text Overlays

The editing subsystem supports non-destructive layering through RecorderImageOverlay and RecorderTextOverlay structures. Users can programmatically define overlays with precise timing:

let logoOverlay = RecorderImageOverlay(
    path: Bundle.main.path(forResource: "logo", ofType: "png")!,
    start: 0,            // overlay appears at the very start
    end: nil,            // stays until the end of the video
    position: .bottomRight,
    opacity: 0.8
)

Text overlays support timestamped visibility windows:

let caption = RecorderTextOverlay(
    text: "Important Point",
    start: 12,           // appears at 12 seconds
    end: 18,             // disappears at 18 seconds
    font: .systemFont(ofSize: 24),
    color: .white,
    position: .center
)

Non-Destructive Trimming

RecorderEditDocument provides trimStart and trimEnd properties that define playback boundaries without discarding source material. The model stores these values alongside overlay arrays for full editing history preservation.

Preset Persistence

RecorderPresetImageStore.swift serializes overlay configurations to disk, enabling rapid reuse of watermark and caption setups. Save presets using:

let preset = RecorderEditPreset(
    name: "Logo-watermarked",
    document: RecorderEditDocument(
        images: [logoOverlay],
        texts: [],
        trimStart: 0,
        trimEnd: nil,
        keepsSystemAudio: true,
        keepsMicrophone: false
    )
)

try RecorderPresetImageStore(directory: presetStoreURL).save(preset)

Pause Handling and Timeline Optimization

RecorderPauseTimeline records pause and resume events during capture sessions. When the screen capture and recording feature finalizes output, this component omits silent gaps from the video track while preserving temporal alignment for overlays that reference absolute timestamps.

Programmatic Usage Examples

Exporting Captured Content

Complete the workflow by exporting processed takes to the user's Movies directory:

let take = RecorderTakeStore.shared.currentTake
let destination = FileManager.default.urls(
    for: .moviesDirectory, in: .userDomainMask
).first!.appendingPathComponent("MyCapture.mov")

try RecorderExporter.export(take, to: destination)

Integrating Editor Views

The UI layer exposes RecorderEditorView for drag-and-drop overlay placement and RecorderInspector.swift for detailed parameter adjustment. These components bind directly to RecorderEditDocument instances, ensuring model-view synchronization during editing sessions.

Summary

• Modular Architecture – The screen capture and recording feature separates concerns across ScreenRecorderService, RecorderComposer, and RecorderExporter for maintainable code organization.
• Flexible Capture Sources – Supports full-screen, window-specific, or regional recording with optional system audio and microphone mixing.
• Professional Editing Tools – Non-destructive trimming, timed image overlays, and text captions with precise start/end controls via RecorderEditDocument.
• Robust Export System – Two-phase staging with RecorderSupport.stagingURL and commitExport prevents data loss during file writes.
• Preset Workflows – RecorderPresetImageStore enables rapid reuse of overlay configurations across recording sessions.

Frequently Asked Questions

How do I programmatically start and stop recording in Vorssaint Utils?

Invoke ScreenRecorderService.shared.toggle() to toggle recording state. This singleton method automatically starts capture if idle or finalizes the current take if already recording, handling all session lifecycle management internally.

What types of overlays does the screen capture feature support?

The system supports image overlays through RecorderImageOverlay for logos and watermarks, and text overlays through RecorderTextOverlay for captions and annotations. Both types accept start and end timestamps to control visibility windows within the video timeline.

Can I capture system audio and microphone simultaneously?

Yes. The RecorderEditDocument configuration includes boolean flags keepsSystemAudio and keepsMicrophone that allow independent control of audio sources. ScreenRecorderService initializes separate audio taps for each stream when these flags are enabled.

How does the export staging process prevent file corruption?

RecorderExporter writes frames to a temporary staging URL provided by RecorderSupport.stagingURL during active recording. Only upon successful completion does RecorderSupport.commitExport atomically move the finalized media to the destination path, ensuring that incomplete captures never overwrite existing files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}