capso-screenshot-macos

Capso Screenshot & Screen Recording Skill

Skill by ara.so — Daily 2026 Skills collection.

Capso is a fully native, open-source macOS screenshot and screen recording app — a free alternative to CleanShot X. Built with Swift 6.0 and SwiftUI targeting macOS 15.0+. Its key strength for developers is a modular SPM architecture: 8 independent packages (CaptureKit, AnnotationKit, OCRKit, etc.) you can embed individually in your own app.

---

Installation

Download Pre-built App

# Homebrew (recommended)
brew tap lzhgus/tap
brew install --cask capso

Or download the signed DMG from GitHub Releases.

Build from Source

Requirements: Xcode 16+, macOS 15.0+, XcodeGen

brew install xcodegen

git clone https://github.com/lzhgus/Capso.git
cd Capso
xcodegen generate
open Capso.xcodeproj
# Press Cmd+R to build and run

CLI build:

xcodegen generate
xcodebuild -project Capso.xcodeproj \
  -scheme Capso \
  -configuration Release \
  build

---

Project Architecture

Capso/
├── App/                     # Thin SwiftUI + AppKit shell
│   ├── CapsoApp.swift       # @main entry point
│   ├── MenuBar/
│   ├── Capture/
│   ├── Recording/
│   ├── Camera/
│   ├── AnnotationEditor/
│   ├── OCR/
│   ├── QuickAccess/
│   └── Preferences/
├── Packages/
│   ├── SharedKit/           # Settings, permissions, utilities
│   ├── CaptureKit/          # ScreenCaptureKit wrapper
│   ├── RecordingKit/        # Screen recording engine
│   ├── CameraKit/           # AVFoundation webcam capture
│   ├── AnnotationKit/       # Drawing/annotation system
│   ├── OCRKit/              # Vision framework OCR
│   ├── ExportKit/           # Video/GIF/image export
│   └── EffectsKit/          # Cursor effects, click highlights
└── project.yml              # XcodeGen project definition

The app shell is intentionally thin — all logic lives in packages. This means you can pull individual packages into your own app via SPM.

---

Using Capso Packages in Your Own App

Add a package as a local or remote SPM dependency in your Package.swift:

// Package.swift
let package = Package(
    name: "MyApp",
    platforms: [.macOS(.v15)],
    dependencies: [
        // Remote (once published to a registry or via exact path)
        .package(path: "../Capso/Packages/CaptureKit"),
        .package(path: "../Capso/Packages/AnnotationKit"),
        .package(path: "../Capso/Packages/OCRKit"),
    ],
    targets: [
        .target(
            name: "MyApp",
            dependencies: [
                "CaptureKit",
                "AnnotationKit",
                "OCRKit",
            ]
        ),
    ]
)

---

Package API Examples

CaptureKit — Screen Capture

CaptureKit wraps ScreenCaptureKit for area, fullscreen, and window capture.

import CaptureKit

// Area capture
let captureManager = CaptureManager()

// Fullscreen capture
Task {
    let image: NSImage = try await captureManager.captureFullscreen()
    // use image
}

// Window capture — pass SCWindow from ScreenCaptureKit
Task {
    let content = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
    if let window = content.windows.first {
        let image: NSImage = try await captureManager.captureWindow(window)
    }
}

// Area capture with a selection rect
Task {
    let rect = CGRect(x: 100, y: 100, width: 800, height: 600)
    let image: NSImage = try await captureManager.captureArea(rect)
}

RecordingKit — Screen Recording

import RecordingKit

let recorder = ScreenRecorder()

// Configure recording
var config = RecordingConfiguration()
config.includesSystemAudio = true
config.includesMicrophone = false
config.outputFormat = .mp4   // or .gif
config.quality = .maximum    // .social, .web

// Start recording a region
Task {
    let outputURL = URL(fileURLWithPath: "/tmp/recording.mp4")
    try await recorder.startRecording(
        region: CGRect(x: 0, y: 0, width: 1920, height: 1080),
        to: outputURL,
        configuration: config
    )
}

// Pause / resume
recorder.pause()
recorder.resume()

// Stop and get final URL
Task {
    let finalURL = try await recorder.stopRecording()
    print("Saved to \(finalURL)")
}

CameraKit — Webcam PiP

import CameraKit

let cameraManager = CameraManager()

// Request permission and start preview
Task {
    let granted = await cameraManager.requestPermission()
    guard granted else { return }
    
    // Get AVCaptureVideoPreviewLayer for embedding in a view
    let previewLayer = try await cameraManager.startCapture()
    
    // Set PiP shape
    cameraManager.pipShape = .circle      // .circle, .square, .portrait, .landscape
}

// Stop capture
cameraManager.stopCapture()

AnnotationKit — Drawing & Annotation

import AnnotationKit

// Create an annotation canvas over an NSImage
let sourceImage = NSImage(named: "screenshot")!
let canvas = AnnotationCanvas(image: sourceImage)

// Add annotations programmatically
let arrow = ArrowAnnotation(
    from: CGPoint(x: 50, y: 50),
    to: CGPoint(x: 200, y: 200),
    color: .red,
    strokeWidth: 3
)
canvas.addAnnotation(arrow)

let rect = RectangleAnnotation(
    frame: CGRect(x: 100, y: 100, width: 300, height: 150),
    color: .blue,
    strokeWidth: 2,
    filled: false
)
canvas.addAnnotation(rect)

let text = TextAnnotation(
    text: "Look here!",
    position: CGPoint(x: 110, y: 110),
    fontSize: 18,
    color: .white
)
canvas.addAnnotation(text)

// Undo / redo
canvas.undo()
canvas.redo()

// Export annotated image
let result: NSImage = canvas.renderToImage()

Screenshot Beautification (AnnotationKit)

import AnnotationKit

let beautifier = ScreenshotBeautifier(image: rawImage)
beautifier.backgroundColor = .systemBlue   // or gradient/custom
beautifier.padding = 40
beautifier.cornerRadius = 12
beautifier.shadowRadius = 20
beautifier.shadowOpacity = 0.4

let beautified: NSImage = beautifier.render()

OCRKit — Text Recognition

import OCRKit

let ocrEngine = OCREngine()

// Instant OCR on an NSImage — returns plain text
Task {
    let text: String = try await ocrEngine.recognizeText(in: image)
    print(text)
    // Copy to clipboard
    NSPasteboard.general.clearContents()
    NSPasteboard.general.setString(text, forType: .string)
}

// Visual OCR — returns bounding boxes + text for each block
Task {
    let blocks: [OCRTextBlock] = try await ocrEngine.recognizeBlocks(in: image)
    for block in blocks {
        print("Text: \(block.text), Bounds: \(block.boundingBox)")
    }
}

ExportKit — Video & GIF Export

import ExportKit

let exporter = MediaExporter()

// Export recorded video with quality preset
Task {
    let inputURL = URL(fileURLWithPath: "/tmp/raw_recording.mp4")
    let outputURL = URL(fileURLWithPath: "/tmp/final.mp4")
    
    try await exporter.exportVideo(
        from: inputURL,
        to: outputURL,
        quality: .social   // .maximum, .social, .web
    )
}

// Export as GIF
Task {
    let inputURL = URL(fileURLWithPath: "/tmp/raw_recording.mp4")
    let outputURL = URL(fileURLWithPath: "/tmp/output.gif")
    
    try await exporter.exportGIF(
        from: inputURL,
        to: outputURL,
        fps: 15,
        scale: 0.75
    )
}

SharedKit — Permissions & Settings

import SharedKit

// Check and request screen recording permission
let permissionManager = PermissionManager()

Task {
    let hasScreen = await permissionManager.requestScreenRecordingPermission()
    let hasCamera = await permissionManager.requestCameraPermission()
    let hasMic = await permissionManager.requestMicrophonePermission()
}

// Access shared app settings
let settings = CapsoSettings.shared
settings.screenshotShortcut = "⌘⇧4"
settings.defaultSaveLocation = URL(fileURLWithPath: "/Users/me/Screenshots")
settings.showCountdownBeforeRecording = true
settings.countdownSeconds = 3

---

SwiftUI Integration Pattern

Embed a capture button in a SwiftUI view:

import SwiftUI
import CaptureKit
import AnnotationKit

struct ContentView: View {
    @State private var capturedImage: NSImage?
    @State private var showAnnotationEditor = false
    private let captureManager = CaptureManager()

    var body: some View {
        VStack {
            if let img = capturedImage {
                Image(nsImage: img)
                    .resizable()
                    .scaledToFit()
                    .frame(maxWidth: 600)
                
                Button("Annotate") {
                    showAnnotationEditor = true
                }
            }

            Button("Capture Fullscreen") {
                Task {
                    capturedImage = try? await captureManager.captureFullscreen()
                }
            }
        }
        .sheet(isPresented: $showAnnotationEditor) {
            if let img = capturedImage {
                // Hypothetical SwiftUI wrapper around AnnotationCanvas
                AnnotationEditorView(image: img) { annotated in
                    capturedImage = annotated
                    showAnnotationEditor = false
                }
            }
        }
    }
}

---

Running Package Tests

Each package is independently testable:

swift test --package-path Packages/SharedKit
swift test --package-path Packages/CaptureKit
swift test --package-path Packages/AnnotationKit
swift test --package-path Packages/OCRKit
swift test --package-path Packages/RecordingKit
swift test --package-path Packages/CameraKit
swift test --package-path Packages/ExportKit
swift test --package-path Packages/EffectsKit

---

Required Entitlements & Info.plist

Your app using Capso packages needs these permissions:

<!-- Info.plist -->
<key>NSScreenCaptureUsageDescription</key>
<string>Required for screenshot and screen recording.</string>

<key>NSCameraUsageDescription</key>
<string>Required for webcam PiP during screen recording.</string>

<key>NSMicrophoneUsageDescription</key>
<string>Required to capture microphone audio during recording.</string>

<!-- App.entitlements -->
<key>com.apple.security.device.camera</key>
<true/>
<key>com.apple.security.device.microphone</key>
<true/>
<!-- Screen capture is runtime-only via TCC, no entitlement needed -->

---

Common Patterns

Pin Screenshot to Screen (Always-on-Top)

import AppKit

func pinScreenshot(_ image: NSImage) {
    let window = NSPanel(
        contentRect: NSRect(x: 100, y: 100, width: image.size.width, height: image.size.height),
        styleMask: [.nonactivatingPanel, .titled, .closable, .resizable],
        backing: .buffered,
        defer: false
    )
    window.level = .floating           // Always on top
    window.isFloatingPanel = true
    window.hidesOnDeactivate = false
    window.contentView = NSImageView(image: image)
    window.makeKeyAndOrderFront(nil)
}

Global Keyboard Shortcut (via SharedKit pattern)

import Carbon
import AppKit

// Register a global hotkey for area capture
func registerCaptureHotkey() {
    NSEvent.addGlobalMonitorForEvents(matching: .keyDown) { event in
        // Check for ⌘⇧4
        if event.modifierFlags.contains([.command, .shift]),
           event.keyCode == 21 { // keyCode 21 = '4'
            NotificationCenter.default.post(name: .startAreaCapture, object: nil)
        }
    }
}

extension Notification.Name {
    static let startAreaCapture = Notification.Name("startAreaCapture")
}

---

Troubleshooting

xcodegen generate fails

• Ensure XcodeGen ≥ 2.40: brew upgrade xcodegen
• Check project.yml is not modified with invalid YAML syntax
• Run xcodegen generate --spec project.yml for explicit path

"Screen Recording permission denied" at runtime

• Go to System Settings → Privacy & Security → Screen Recording and enable Capso
• For your own app using CaptureKit, you must trigger the permission prompt first via PermissionManager.requestScreenRecordingPermission()

Build errors with Swift 6 concurrency

• Capso targets Swift 6 strict concurrency. Ensure all closures that touch UI are @MainActor
• Add @preconcurrency import for ScreenCaptureKit if you see warnings in Xcode 16

GIF export is slow

• Lower the fps (e.g. fps: 10) and scale (e.g. scale: 0.5) in ExportKit
• Use .web quality preset for faster encoding

Camera not showing in PiP

• Verify camera permission is granted in System Settings
• Call CameraManager.requestPermission() before startCapture()
• Ensure your entitlement includes com.apple.security.device.camera

---

License Note

Capso uses Business Source License 1.1:

• ✅ Personal use, internal company use, forking, modifying
• ❌ Selling a competing screen-capture product based on this code
• ✅ Automatically becomes Apache 2.0 in 2029 per release

When embedding packages in your own non-competing app, you are permitted under BSL 1.1.

---

Key Links

• GitHub Repository
• Releases / Download
• Website
• Bug Reports
• Feature Requests
• GitHub Sponsors