Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

11.5 KB
Raw Blame
import AppKit
import CoreGraphics
import Foundation
import OpenScreenCaptureCore
import ScreenCaptureKit

/// `--picker-session`: Apple's system picker, and every take recorded from what it returns.
///
/// Why a session instead of the usual one process per take:
///
/// - A capture that starts from `SCContentSharingPicker` needs no Screen Recording grant and
///   never raises macOS 15's "bypass the system private window picker" alert: the user's
///   pick is the consent. Measured on macOS 26.5 for display and window picks, from a
///   helper process like this one.
/// - That consent lives in the `SCContentFilter` the picker hands back, and a filter cannot
///   leave the process (it is not NSSecureCoding). So the process that asked has to be the
///   one that records -- and has to stay alive to record the same source again without
///   asking the user to pick it again for every take.
///
/// Each take still gets its own `ScreenCaptureRecorder` and its own `SCStream`, so pause,
/// the audio timeline and the writer behave exactly as in the single-take helper.
///
/// Protocol: one command per stdin line (`PickerSessionCommand`), events on stdout as
/// everywhere else, plus `picker-session-ready`, `picker-presented`, `picker-selected`,
/// `picker-cancelled`, `picker-failed` and `take-ended`. Closing stdin ends the session: nothing here may
/// outlive the app.
///
/// 15.2, not 14.0 where the picker API starts: `includedDisplays` and `includedWindows`
/// arrive in 15.2, and without them the pick cannot be mapped to a screen position, which
/// the cursor telemetry needs. Before 15.2 the app keeps its own picker.
///
/// `@unchecked Sendable`: every piece of state here is read and written on the main queue
/// only -- commands and picker callbacks are all hopped onto it before they touch anything.
@available(macOS 15.2, *)
final class PickerSession: NSObject, SCContentSharingPickerObserver, @unchecked Sendable {
	private var picked: PickedSource?
	/// Whether the picker, as last shown, left out the whole app that owns this helper.
	private var presentedExcludesApp = false
	/// Whether a `present` is waiting for its answer. While the shared picker is active,
	/// macOS can deliver a selection outside any presentation of ours (the menu-bar
	/// sharing item, or a pick replayed from an earlier session): that is not an answer to
	/// anything the app asked, and reporting it recorded a window nobody chose (#1013).
	private var awaitingPick = false
	private var recorder: ScreenCaptureRecorder?

	func run() -> Never {
		let app = NSApplication.shared
		// No Dock icon and no menu bar: the picker is system UI and needs no window here.
		app.setActivationPolicy(.accessory)
		SCContentSharingPicker.shared.add(self)

		let reader = Thread {
			while let line = readLine() {
				guard let command = parsePickerSessionCommand(line) else {
					emit([
						"event": "warning",
						"code": "picker-session-unknown-command",
						"message": line,
					])
					continue
				}
				DispatchQueue.main.async { self.handle(command) }
			}
			// stdin closed: the app is gone, or never meant to keep us.
			DispatchQueue.main.async { self.shutdown() }
		}
		reader.start()

		emit(["event": "picker-session-ready"])
		app.run()
		exit(0)
	}

	private func handle(_ command: PickerSessionCommand) {
		switch command {
		case .present(let excludedWindowIDs, let modes, let hideDesktopIcons):
			present(excludedWindowIDs: excludedWindowIDs, modes: modes, hideDesktopIcons: hideDesktopIcons)
		case .start(let request):
			startTake(request)
		case .pause:
			recorder?.pause()
		case .resume:
			recorder?.resume()
		case .stop:
			stopTake()
		case .quit:
			shutdown()
		}
	}

	// MARK: - Picker

	private func present(excludedWindowIDs: [Int], modes: [PickerMode], hideDesktopIcons: Bool) {
		var configuration = SCContentSharingPickerConfiguration()
		var allowed: SCContentSharingPickerMode = []
		if modes.contains(.display) { allowed.insert(.singleDisplay) }
		if modes.contains(.window) { allowed.insert(.singleWindow) }
		configuration.allowedPickerModes = allowed
		// Swapping the source mid-take would change the frame size under a writer whose
		// dimensions are fixed when the take starts. A new source is a new pick.
		configuration.allowsChangingSelectedContent = false
		// A picked display filter hides this process's own windows, but not the app's:
		// the HUD and the notes window belong to Electron. Measured: a window owned by the
		// parent app shows in the capture unless it is listed here.
		configuration.excludedWindowIDs =
			excludedWindowIDs + Self.finderDesktopIconWindowIDs(hideDesktopIcons: hideDesktopIcons)
		// By app, not by window: a banner is a window created after the pick, so no id
		// list taken now could name it. The same goes for the app's HUD, which is a new
		// window after every trip through the editor: a pick made in Record mode, before
		// that HUD exists, has to leave the app out whole to still be usable at Start (#996).
		let appBundleID = NSRunningApplication(processIdentifier: getppid())?.bundleIdentifier
		configuration.excludedBundleIDs = [notificationCenterBundleID] + [appBundleID].compactMap { $0 }
		presentedExcludesApp = appBundleID != nil

		// Off, then on: the shared picker keeps its state across presentations, and a
		// picker left active from an earlier pick can hand that pick back as a new answer
		// (#1013). Each presentation starts from a fresh activation -- unless a take is
		// running, whose stream deactivating the picker could end.
		let picker = SCContentSharingPicker.shared
		if recorder == nil {
			picker.isActive = false
		}
		picker.defaultConfiguration = configuration
		picker.isActive = true
		awaitingPick = true
		picker.present()
		emit(["event": "picker-presented"])
	}

	func contentSharingPicker(
		_ picker: SCContentSharingPicker,
		didUpdateWith filter: SCContentFilter,
		for stream: SCStream?
	) {
		DispatchQueue.main.async { self.didPick(filter, stream: stream) }
	}

	func contentSharingPicker(_ picker: SCContentSharingPicker, didCancelFor stream: SCStream?) {
		DispatchQueue.main.async {
			// A cancel for a running stream is the user stopping it from the menu bar, which
			// the take's own stop path already reports.
			if stream == nil, self.awaitingPick {
				self.awaitingPick = false
				emit(["event": "picker-cancelled"])
			}
		}
	}

	func contentSharingPickerStartDidFailWithError(_ error: Error) {
		DispatchQueue.main.async {
			self.awaitingPick = false
			emit([
				"event": "picker-failed",
				"message": "\(error)",
			])
		}
	}

	private func didPick(_ filter: SCContentFilter, stream: SCStream?) {
		// Updates for an existing stream are Apple's "change what you share", switched off
		// by allowsChangingSelectedContent; one that arrives anyway must not swap the source.
		guard stream == nil else {
			return
		}
		// A pick nobody asked for must not replace the retained one either.
		guard awaitingPick else {
			emit([
				"event": "warning",
				"code": "picker-unrequested-pick",
				"message": "Ignored a picker selection made outside a presentation.",
			])
			return
		}
		awaitingPick = false

		let display = filter.includedDisplays.first
		let window = filter.includedWindows.first
		let frame = window?.frame ?? display?.frame ?? filter.contentRect
		let displayId = display?.displayID ?? Self.display(containing: frame)
		picked = PickedSource(filter: filter, frame: frame, displayId: displayId)

		var event: [String: Any] = [
			"event": "picker-selected",
			"kind": window != nil ? "window" : "display",
			"bounds": [
				"x": frame.origin.x,
				"y": frame.origin.y,
				"width": frame.size.width,
				"height": frame.size.height,
			],
			"pointPixelScale": filter.pointPixelScale,
			// Tells the app this pick also leaves out windows it opens later, so it need
			// not ask again when the HUD comes back as a new one.
			"excludesApp": presentedExcludesApp,
		]
		if let displayId {
			event["displayId"] = displayId
		}
		if let window {
			event["windowId"] = window.windowID
			event["title"] = window.title ?? ""
			event["appName"] = window.owningApplication?.applicationName ?? ""
		}
		emit(event)
	}

	/// Finder's desktop-icon windows, read from the window server: `SCShareableContent` would
	/// need the Screen Recording grant the picker exists to avoid. Owner and level are
	/// readable without it. The icons stay put for the whole session, so ids taken at pick
	/// time hold -- unless Finder relaunches, which gives them new ones.
	/// Not named `desktopIconWindowIDs`: inside this class that name would shadow the
	/// OpenScreenCaptureCore function it calls.
	private static func finderDesktopIconWindowIDs(hideDesktopIcons: Bool) -> [Int] {
		guard hideDesktopIcons,
			let entries = CGWindowListCopyWindowInfo([.optionOnScreenOnly], kCGNullWindowID)
				as? [[String: Any]]
		else {
			return []
		}
		let candidates = entries.compactMap { entry -> CaptureWindowCandidate? in
			guard let number = entry[kCGWindowNumber as String] as? Int,
				let pid = entry[kCGWindowOwnerPID as String] as? Int32
			else {
				return nil
			}
			return CaptureWindowCandidate(
				windowID: UInt32(number),
				bundleID: NSRunningApplication(processIdentifier: pid)?.bundleIdentifier,
				layer: entry[kCGWindowLayer as String] as? Int ?? 0
			)
		}
		return OpenScreenCaptureCore.desktopIconWindowIDs(candidates).map { Int($0) }
	}

	private static func display(containing frame: CGRect) -> CGDirectDisplayID? {
		var displays = [CGDirectDisplayID](repeating: 0, count: 8)
		var count: UInt32 = 0
		let center = CGRect(x: frame.midX, y: frame.midY, width: 1, height: 1)
		guard CGGetDisplaysWithRect(center, UInt32(displays.count), &displays, &count) == .success,
			count > 0
		else {
			return nil
		}
		return displays[0]
	}

	// MARK: - Takes

	private func startTake(_ requestData: Data) {
		guard recorder == nil else {
			emitError(code: "take-already-running", message: "A take is already recording in this session.")
			return
		}
		guard let picked else {
			emitError(code: "no-source-picked", message: "Nothing was picked in the system picker yet.")
			emit(["event": "take-ended"])
			return
		}

		let request: RecordingRequest
		do {
			request = try JSONDecoder().decode(RecordingRequest.self, from: requestData)
		} catch {
			emitError(code: "helper-error", message: "\(error)")
			emit(["event": "take-ended"])
			return
		}

		let recorder = ScreenCaptureRecorder(request: request, picked: picked)
		self.recorder = recorder
		let take = ObjectIdentifier(recorder)
		Task {
			do {
				try await recorder.start()
			} catch {
				// Same code the single-take helper reports on its way out, so the app reads a
				// failed start the same way on both paths.
				let message = (error as? HelperError)?.description ?? "\(error)"
				emitError(code: "helper-error", message: message)
				await recorder.stop()
				DispatchQueue.main.async { self.finishTake(take) }
			}
		}
	}

	private func stopTake() {
		guard let recorder else {
			emit(["event": "take-ended"])
			return
		}
		let take = ObjectIdentifier(recorder)
		Task {
			await recorder.stop()
			DispatchQueue.main.async { self.finishTake(take) }
		}
	}

	/// The session's replacement for the single-take helper exiting: the one event that
	/// says this take's output is complete.
	private func finishTake(_ finished: ObjectIdentifier) {
		guard let current = recorder, ObjectIdentifier(current) == finished else {
			return
		}
		recorder = nil
		emit(["event": "take-ended"])
	}

	private func shutdown() {
		SCContentSharingPicker.shared.isActive = false
		guard let recorder else {
			exit(0)
		}
		Task {
			await recorder.stop()
			exit(0)
		}
	}
}