capso-screenshot-macos

# Capso Screenshot & Screen Recording Skill > Skill by [ara.so](https://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 ```bash # Homebrew (recommended) brew tap lzhgus/tap brew install --cask capso ``` Or download the signed DMG from [GitHub Releases](https://github.com/lzhgus/Capso/releases/latest). ### Build from Source **Requirements:** Xcode 16+, macOS 15.0+, XcodeGen ```bash 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:** ```bash 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`: ```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. ```swift 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 ```swift 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 ```swift 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 ```swift 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) ```swift 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 ```swift 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 ```swift 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 ```swift 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: ```swift 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: ```bash 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: ```xml <!-- 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> ``` ```xml <!-- 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) ```swift 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) ```swift 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](https://github.com/lzhgus/Capso) - [Releases / Download](https://github.com/lzhgus/Capso/releases/latest) - [Website](https://www.awesomemacapp.com/app/capso) - [Bug Reports](https://github.com/lzhgus/Capso/issues/new?template=bug_report.yml) - [Feature Requests](https://github.com/lzhgus/Capso/issues/new?template=feature_request.yml) - [GitHub Sponsors](https://github.com/sponsors/lzhgus)