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

> Explore Vorssaint Utils screen capture and recording features. Get full-screen, window, or regional capture with audio, overlays, and non-destructive editing. Swift architecture for robust performance.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: deep-dive
- Published: 2026-09-09

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```swift
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:

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/RecorderPresetImageStore.swift) serializes overlay configurations to disk, enabling rapid reuse of watermark and caption setups. Save presets using:

```swift
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:

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.