Skip to content

Open source CapCut alternative.

TypeScript

feat(app): screen recordings draw the pointer [rebuild]

David Le54ed86e7633a
diff --git a/apps/Donkey/Sources/Donkey/ScreenRecordingController.swift b/apps/Donkey/Sources/Donkey/ScreenRecordingController.swift
index 20ac1f85..c82b540d 100644
--- a/apps/Donkey/Sources/Donkey/ScreenRecordingController.swift
+++ b/apps/Donkey/Sources/Donkey/ScreenRecordingController.swift
@@ -30,9 +30,6 @@ final class ScreenRecordingController {
private let recordingDim = RecordingRegionDimOverlayController()
private var recorder: (any ScreenRecording)?
- /// The pointer's path through the recording. The video never draws a cursor, so this is the only
- /// record of where it went — an editor draws its own, or zooms to follow it.
- private let cursorTrack = CursorTrackRecorder()
private var phase: Phase = .idle
private var armScreen: NSScreen?
private var selectedRegion: (rect: CGRect, displayID: CGDirectDisplayID)?
@@ -216,7 +213,6 @@ final class ScreenRecordingController {
do {
try await recorder.start(configuration)
- cursorTrack.start(captureRect: Self.captureRectProvider(for: target))
phase = .recording
recordingStart = Date()
model.isRecording = true
@@ -242,10 +238,8 @@ final class ScreenRecordingController {
Task {
defer { finishAfterRecording() }
- let track = cursorTrack.finish()
do {
let url = try await recorder.stop()
- Self.writeCursorTrack(track, beside: url)
NSWorkspace.shared.activateFileViewerSelecting([url])
} catch {
model.statusMessage = "Recording failed to finalize."
@@ -255,7 +249,6 @@ final class ScreenRecordingController {
private func handleUnexpectedStop() {
stopTimer()
- _ = cursorTrack.finish()
recorder = nil
recordingDim.close()
phase = .idle
@@ -291,38 +284,6 @@ final class ScreenRecordingController {
}
}
- // MARK: - Cursor track
-
- /// The rect the pointer is measured against, in CoreGraphics global points. It is read on every
- /// sample, so a window dragged mid-recording keeps yielding positions in its own frame.
- private static func captureRectProvider(for target: ScreenCaptureTarget) -> @MainActor () -> CGRect? {
- switch target {
- case .display(let displayID, let region):
- let bounds = CGDisplayBounds(displayID)
- let rect = region.map { $0.offsetBy(dx: bounds.minX, dy: bounds.minY) } ?? bounds
- return { rect }
- case .window(let windowID):
- return { windowFrame(windowID) }
- }
- }
-
- /// A window's frame right now, straight from the window server.
- private static func windowFrame(_ windowID: CGWindowID) -> CGRect? {
- guard let list = CGWindowListCopyWindowInfo([.optionIncludingWindow], windowID) as? [[String: Any]],
- let bounds = list.first?[kCGWindowBounds as String] as? [String: CGFloat],
- let rect = CGRect(dictionaryRepresentation: bounds as CFDictionary) else {
- return nil
- }
- return rect
- }
-
- private static func writeCursorTrack(_ track: CursorTrack, beside movieURL: URL) {
- guard !track.samples.isEmpty else { return }
- let encoder = JSONEncoder()
- guard let data = try? encoder.encode(track) else { return }
- try? data.write(to: ScreenRecordingDestination.cursorTrackURL(for: movieURL))
- }
-
// MARK: - Audio inputs
/// The audio sources offered by the input picker: system output (the default), every available
diff --git a/apps/Donkey/Sources/DonkeyRuntime/CursorTrack.swift b/apps/Donkey/Sources/DonkeyRuntime/CursorTrack.swift
deleted file mode 100644
index 4737add7..00000000
--- a/apps/Donkey/Sources/DonkeyRuntime/CursorTrack.swift
+++ /dev/null
@@ -1,137 +0,0 @@
-import CoreGraphics
-import Foundation
-
-/// One reading of the pointer during a recording: where it sat in the recorded frame and whether a
-/// button was down. Positions are fractions of the frame (0…1) from its top-left corner, so a track
-/// survives any scale the video is exported at.
-public struct CursorSample: Codable, Equatable, Sendable {
- /// Seconds from the moment capture started.
- public let t: Double
- public let x: Double
- public let y: Double
- /// Any mouse button held at this reading — the beat an auto-zoom wants to land on.
- public let pressed: Bool
- /// Whether the pointer was inside the recorded frame. `x`/`y` stay unclamped when it is not, so a
- /// consumer can tell "just off the left edge" from "parked at the left edge".
- public let inside: Bool
-
- public init(t: Double, x: Double, y: Double, pressed: Bool, inside: Bool) {
- self.t = t
- self.x = x
- self.y = y
- self.pressed = pressed
- self.inside = inside
- }
-}
-
-/// The pointer's path through a recording, written beside the `.mov`. The video itself never draws a
-/// cursor: the path rides as data so an editor can draw its own pointer, follow it with a zoom, or
-/// ignore it.
-public struct CursorTrack: Codable, Equatable, Sendable {
- public static let version = 1
-
- public let version: Int
- /// Readings per second the recorder aimed for. Samples are dropped while nothing moves, so the
- /// gaps between them are uneven; hold the last reading across a gap.
- public let sampleRate: Int
- /// The recorded frame in points, the rect the fractions are measured against.
- public let frameWidth: Double
- public let frameHeight: Double
- public let samples: [CursorSample]
-
- public init(sampleRate: Int, frameSize: CGSize, samples: [CursorSample]) {
- self.version = Self.version
- self.sampleRate = sampleRate
- self.frameWidth = Double(frameSize.width)
- self.frameHeight = Double(frameSize.height)
- self.samples = samples
- }
-}
-
-/// Samples the pointer for the length of a recording. The capture rect is asked for on every reading
-/// rather than captured once, so a window that gets dragged mid-recording still yields positions in
-/// its own frame.
-@MainActor
-public final class CursorTrackRecorder {
- private let sampleRate: Int
- private var captureRect: (@MainActor () -> CGRect?)?
- private var timer: Timer?
- private var startedAt: Date?
- private var samples: [CursorSample] = []
- private var frameSize: CGSize = .zero
- private var last: (x: Double, y: Double, pressed: Bool, inside: Bool)?
-
- public init(sampleRate: Int = 60) {
- self.sampleRate = max(1, sampleRate)
- }
-
- /// Begin sampling. `captureRect` answers in CoreGraphics global points (top-left origin) — the
- /// space `SCWindow.frame` and `CGDisplayBounds` report.
- public func start(captureRect: @escaping @MainActor () -> CGRect?) {
- stopTimer()
- self.captureRect = captureRect
- samples = []
- last = nil
- frameSize = captureRect()?.size ?? .zero
- startedAt = Date()
- sample()
- let timer = Timer(timeInterval: 1.0 / Double(sampleRate), repeats: true) { [weak self] _ in
- Task { @MainActor in self?.sample() }
- }
- RunLoop.main.add(timer, forMode: .common)
- self.timer = timer
- }
-
- /// Stop sampling and hand back what was recorded.
- public func finish() -> CursorTrack {
- stopTimer()
- let track = CursorTrack(sampleRate: sampleRate, frameSize: frameSize, samples: samples)
- captureRect = nil
- startedAt = nil
- samples = []
- last = nil
- return track
- }
-
- private func sample() {
- guard let startedAt, let rect = captureRect?(), rect.width > 0, rect.height > 0 else { return }
- frameSize = rect.size
- let point = Self.cursorLocation()
- let x = Double((point.x - rect.minX) / rect.width)
- let y = Double((point.y - rect.minY) / rect.height)
- let pressed = Self.anyButtonDown()
- let inside = (0...1).contains(x) && (0...1).contains(y)
- let reading = (x: round(x), y: round(y), pressed: pressed, inside: inside)
- // A still pointer writes nothing: the track keeps its turns, not its idle time.
- if let last, last == reading { return }
- last = reading
- samples.append(CursorSample(
- t: Date().timeIntervalSince(startedAt),
- x: reading.x,
- y: reading.y,
- pressed: pressed,
- inside: inside
- ))
- }
-
- /// Fractions to five places — a pixel on an 8K frame, and it keeps the sidecar small.
- private func round(_ value: Double) -> Double {
- (value * 100_000).rounded() / 100_000
- }
-
- private func stopTimer() {
- timer?.invalidate()
- timer = nil
- }
-
- /// The pointer in CoreGraphics global points (top-left origin) — the space the capture rects
- /// come in, straight from the event system with no AppKit in the way.
- private static func cursorLocation() -> CGPoint {
- CGEvent(source: nil)?.location ?? .zero
- }
-
- private static func anyButtonDown() -> Bool {
- let buttons: [CGMouseButton] = [.left, .right, .center]
- return buttons.contains { CGEventSource.buttonState(.combinedSessionState, button: $0) }
- }
-}
diff --git a/apps/Donkey/Sources/DonkeyRuntime/ScreenRecorder.swift b/apps/Donkey/Sources/DonkeyRuntime/ScreenRecorder.swift
index aea5ca41..6fb2eccf 100644
--- a/apps/Donkey/Sources/DonkeyRuntime/ScreenRecorder.swift
+++ b/apps/Donkey/Sources/DonkeyRuntime/ScreenRecorder.swift
@@ -17,8 +17,7 @@ public struct ScreenRecordingConfiguration: Sendable {
public var capturesMicrophone: Bool
/// The microphone device to capture, when `capturesMicrophone` is set. `nil` uses the system default.
public var microphoneDeviceID: String?
- /// Whether the pointer is burned into the video. Off: the recording carries the cursor as a
- /// `CursorTrack` sidecar instead, so an editor can draw it, follow it, or leave it out.
+ /// Whether the pointer is burned into the video.
public var showsCursor: Bool
public var frameRate: Int
/// Window IDs to keep out of the capture — our own control bar, so it never appears in the file.
@@ -30,7 +29,7 @@ public struct ScreenRecordingConfiguration: Sendable {
capturesSystemAudio: Bool = true,
capturesMicrophone: Bool = false,
microphoneDeviceID: String? = nil,
- showsCursor: Bool = false,
+ showsCursor: Bool = true,
frameRate: Int = 30,
excludedWindowIDs: [CGWindowID] = [],
outputURL: URL
diff --git a/apps/Donkey/Sources/DonkeyRuntime/ScreenRecordingDestination.swift b/apps/Donkey/Sources/DonkeyRuntime/ScreenRecordingDestination.swift
index 3c135da4..f85ac8c4 100644
--- a/apps/Donkey/Sources/DonkeyRuntime/ScreenRecordingDestination.swift
+++ b/apps/Donkey/Sources/DonkeyRuntime/ScreenRecordingDestination.swift
@@ -30,12 +30,6 @@ public enum ScreenRecordingDestination {
return candidate
}
- /// Where a recording's cursor track goes: the movie's name with a `.cursor.json` tail, so the
- /// pair travels together and an importer can find one from the other.
- public static func cursorTrackURL(for movieURL: URL) -> URL {
- movieURL.deletingPathExtension().appendingPathExtension("cursor.json")
- }
-
/// The concrete output URL for a recording starting now, on the real Desktop.
public static func makeOutputURL(now: Date = Date()) -> URL {
let fileManager = FileManager.default
diff --git a/apps/Donkey/Tests/DonkeyRuntimeTests/CursorTrackTests.swift b/apps/Donkey/Tests/DonkeyRuntimeTests/CursorTrackTests.swift
deleted file mode 100644
index c19251c1..00000000
--- a/apps/Donkey/Tests/DonkeyRuntimeTests/CursorTrackTests.swift
+++ /dev/null
@@ -1,34 +0,0 @@
-@testable import DonkeyRuntime
-import Foundation
-import Testing
-
-@Suite
-struct CursorTrackTests {
- @Test
- func cursorTrackSitsBesideTheMovie() {
- let movie = URL(fileURLWithPath: "/Users/x/Desktop/Screen Recording 2026-07-21 at 15.24.05.mov")
-
- let sidecar = ScreenRecordingDestination.cursorTrackURL(for: movie)
-
- #expect(sidecar.lastPathComponent == "Screen Recording 2026-07-21 at 15.24.05.cursor.json")
- #expect(sidecar.deletingLastPathComponent() == movie.deletingLastPathComponent())
- }
-
- @Test
- func trackRoundTripsThroughJSON() throws {
- let track = CursorTrack(
- sampleRate: 60,
- frameSize: CGSize(width: 1512, height: 982),
- samples: [
- CursorSample(t: 0, x: 0.5, y: 0.25, pressed: false, inside: true),
- CursorSample(t: 0.5, x: 1.2, y: 0.25, pressed: true, inside: false)
- ]
- )
-
- let decoded = try JSONDecoder().decode(CursorTrack.self, from: JSONEncoder().encode(track))
-
- #expect(decoded == track)
- #expect(decoded.version == CursorTrack.version)
- #expect(decoded.frameWidth == 1512)
- }
-}
diff --git a/docs/guides/swift.md b/docs/guides/swift.md
index a432afd7..4d555ffa 100644
--- a/docs/guides/swift.md
+++ b/docs/guides/swift.md
@@ -27,9 +27,8 @@ Screen recording follows this split: the recorder and its destination types
hold the capture state; the control bar view renders it; controllers own the
AppKit-only work such as the control bar panel, the region and window pickers,
and screen positioning; the app delegate bootstraps the feature and the menu
-bar without owning product behavior. The pointer is captured as data: the
-stream draws no cursor, and a track recorder samples where it went into a
-`.cursor.json` beside the movie for an editor to draw or follow.
+bar without owning product behavior. The stream draws the pointer straight
+into the video.
## Language