The Problem

MacOS users need a free, native tool that can capture screenshots, scroll‑long content, and record video/GIF with webcam‑PiP, without the licensing cost of commercial products. Existing solutions either lack modularity or require paid upgrades for features that power users expect (OCR, annotation, history).

What This Does

Capso delivers a full‑featured screenshot and screen‑recording suite built with Swift 6.0 and SwiftUI. The core app lives in App/Sources/CapsoApp.swift, which launches the AppDelegate (App/Sources/AppDelegate.swift). From there the menu‑bar controller (App/Sources/MenuBar/MenuBarController.swift) opens the main windows:

  • Capture flow – CaptureCoordinator.swift orchestrates ScreenCaptureManager (in Packages/CaptureKit) and presents overlay views (CaptureOverlayView.swift, CaptureOverlayWindow.swift).
  • Annotation – AnnotationEditorView.swift and its canvas (AnnotationCanvasNSView.swift) render drawn objects from Packages/AnnotationKit.
  • Recording – RecordingCoordinator.swift drives ScreenRecorder (Packages/RecordingKit/ScreenRecorder.swift) and shows UI windows (RecordingToolbarWindow.swift, CountdownWindow.swift).
  • OCR – OCRCoordinator.swift uses OCRKit/TextRecognizer.swift to extract text from a selected region.
  • History – HistoryCoordinator.swift persists HistoryEntry objects via HistoryKit/HistoryStore.swift.

Each feature is packaged as an SPM module (e.g., CaptureKit, AnnotationKit, OCRKit) so they can be reused in other projects.

How It Is Wired

  1. Launch – The SwiftUI entry point CapsoApp creates the AppDelegate.
  2. Menu bar – MenuBarController registers a status‑item; user actions call into the corresponding coordinator (CaptureCoordinator, RecordingCoordinator, OCRCoordinator).
  3. Capture pipeline – CaptureCoordinator.startCapture(mode:) selects a CaptureMode (CaptureKit/CaptureMode.swift), then ScreenCaptureManager captures frames. For scrolling captures, ScrollCaptureController stitches screenshots via ScrollStitcher.
  4. Annotation – AnnotationEditorWindow embeds AnnotationEditorView, which hosts AnnotationCanvasNSView. User strokes are turned into AnnotationObject subclasses (ArrowObject, FreehandObject, etc.) and rendered by AnnotationRenderer.
  5. Recording – RecordingCoordinator.beginRecording() creates a ScreenRecorder instance, attaches audio sources, and writes to a temporary file. UI windows (RecordingControlsWindow, CountdownWindow) are updated via Combine publishers in RecordingToolbar.
  6. Export – ExportKit provides MP4Exporter and GIFExporter; the coordinator calls ExportKit.export(recording:options:).
  7. History – After export, HistoryStore.save(entry:) writes metadata to the app’s support directory. The HistoryView reads this store to populate the library UI.

The most connected files are App/Sources/AppDelegate.swift (initial wiring) and the various *Coordinator.swift files (control flow hubs). No circular imports were detected, but deep nesting (up to 8 levels) in the annotation canvas and editor files makes the control flow hard to follow.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Capso.git
cd Capso

# Open the Xcode project (generated by SwiftPM)
swift package generate-xcodeproj
open Capso.xcodeproj

# Build & run (macOS 15+ target)
⌘ R   # or use `xcodebuild -scheme Capso -destination 'platform=macOS,arch=x86_64'`

No external configuration files are required; the app prompts for screen‑recording, camera, and microphone permissions on first use. The README.md documents a Homebrew tap for binary distribution, but building from source follows the steps above.

Real‑World Use

A developer can embed CaptureKit in a custom utility to generate automated screenshots for UI tests:

import CaptureKit

let manager = ScreenCaptureManager()
manager.captureFullScreen { image in
    // process image, e.g. compare to baseline
}

Because the kit is a standalone SwiftPM package, integration is straightforward and does not drag the full UI stack.

Code Health & Issues

  • High – Deep nesting – 28 occurrences (e.g., AnnotationCanvasNSView.swift, AnnotationEditorView.swift, BeautifyPanel.swift).
  • High – Duplicated code – 66 identical 6‑line blocks across 26 window files (CameraPiPWindow.swift, ToastWindow.swift, etc.).
  • Medium – High branching density – 125 branch points in ~408 lines (e.g., AnnotationCanvasNSView.swift, AppDelegate.swift).
  • Low – TODO/FIXME markers – 3 in RecordingSettingsView.swift.

Code‑health audit

  • HIGH – GitHub Actions use tags (softprops/action-gh-release@v2). Pin to a commit SHA to avoid supply‑chain drift.
  • HIGH – Workflow pushes directly to the default branch (build-release.yml). Switch to a bot branch and open a PR or restrict to tags.
  • LOW – No job timeouts defined. Add timeout-minutes to each job to prevent runaway runs.

Test suite (12 test files) and CI (.github/workflows/ci.yml) are present, but the duplicated UI boilerplate and deep nesting increase maintenance cost.

The Bottom Line

Capso provides a solid, modular macOS capture stack with a polished UI, but the codebase suffers from excessive nesting and duplicated window logic, which hampers readability and future change. It is a good candidate for teams that need a free, extensible foundation and are willing to refactor the UI scaffolding. New contributors should prioritize extracting shared window helpers and flattening the annotation editor’s control flow.