Aperture

Record the screen on macOS

Requirements

• macOS 13+
• Xcode 15+
• Swift 5.7+

Install

Add the following to Package.swift:

.package(url: "https://github.com/wulkano/Aperture", from: "3.0.0")

Or add the package in Xcode.

Docs

API Documentation.

Base Usage

import Foundation
import Aperture

let recorder = Aperture.Recorder()

let screens = try await Aperture.Devices.screen()

guard let screen = screens.first else {
	// No screens
	exit(1)
}

try await recorder.start(
	target: .screen,
	options: Aperture.RecordingOptions(
		destination: URL(filePath: "./screen-recording.mp4"),
		targetID: screen.id,
	)
)

try await Task.sleep(for: .seconds(5))

try await recorder.stop()

Base Options

destination

Type: URL

The filepath where the resulting recording should be written to.

targetID

Type: String

The ID of the target to record

Base Audio Options

losslessAudio

Type: Bool
Default: false

Will use the lossless ALAC codec if enabled, AAC otherwise.

recordSystemAudio

Type: Bool
Default: false

Record the system audio.

microphoneDeviceID

Type: String?

A microphone device ID to record.

Base Video Options

framesPerSecond

Type: Int
Default: 60

Number of frames per seconds.

showCursor

Type: Bool
Default: true

Show the cursor in the screen recording.

highlightClicks

Type: Bool
Default: false

Highlight cursor clicks in the screen recording.

Note: This will only apply on macOS 15+

videoCodec

Type: Aperture.VideoCodec
Default: .h264
Values: .h264, .hevc, .proRes422, .proRes4444

The video codec to be used.

Recording a screen

Use Aeprture.Devices.screen to discover the available screens

And then start recording with target: .screen

try await recorder.start(
	target: .screen,
	options: Aperture.RecordingOptions(
		destination: fileURL,
		targetID: screen.id,
		framesPerSecond: 60,
		cropRect: CGRect(x: 10, y: 10, width: 100, height: 100),
		showCursor: true,
		highlightClicks: true,
		videoCodec: .h264,
		losslessAudio: true,
		recordSystemAudio: true,
		microphoneDeviceID: microphone.id,
	)
)

Accepts all the base video and audio options along with:

cropRect

Type: CGRect?

Record only an area of the screen.

Recording a window

Use Aeprture.Devices.window to discover the available windows

And then start recording with target: .window

try await recorder.start(
	target: .window,
	options: Aperture.RecordingOptions(
		destination: fileURL,
		targetID: window.id,
		framesPerSecond: 60,
		showCursor: true,
		highlightClicks: true,
		videoCodec: .h264,
		losslessAudio: true,
		recordSystemAudio: true,
		microphoneDeviceID: microphone.id,
	)
)

Accepts all the base video and audio options

Recording only audio

Use Aeprture.Devices.audio to discover the available audio devices

And then start recording with target: .audioOnly

try await recorder.start(
	target: .audioOnly,
	options: Aperture.RecordingOptions(
		destination: fileURL,
		losslessAudio: true,
		recordSystemAudio: true,
		microphoneDeviceID: microphone.id,
	)
)

Accepts all the base audio options.

Recording an external device

Use Aeprture.Devices.iOS to discover the available external devices

And then start recording with target: .externalDevice

try await recorder.start(
	target: .externalDevice,
	options: Aperture.RecordingOptions(
		destination: fileURL,
		targetID: device.id,
		framesPerSecond: 60,
		videoCodec: .h264,
		losslessAudio: true,
		recordSystemAudio: true,
		microphoneDeviceID: microphone.id,
	)
)

Accepts the base video options except for cursor related ones, and all the audio options.

Discovering Devices

Screens

let screens = try await Aperture.Devices.screen()

Windows

let windows = try await Aperture.Devices.window(excludeDesktopWindows: true, onScreenWindowsOnly: true)

excludeDesktopWindows

Type: Bool
Default: true

onScreenWindowsOnly

Type: Bool
Default: true

Audio Devices

let devices = Aperture.Devices.audio()

External Devices

let devices = Aperture.Devices.iOS()

Dev

Run ./example.sh or ./example-ios.sh.

Related

• aperture-node - Node.js wrapper