VirtualDisplayKit

Warning

This library uses Apple's private CGVirtualDisplay API. Private APIs are not officially supported by Apple and may change between macOS versions. Apps using this library are not suitable for App Store submission without understanding and accepting the risk of rejection. This is intended for internal tools, development utilities, digital signage systems, and direct-distribution applications. See SECURITY.md for more.

Features

Requirements

Installation

Swift Package Manager

dependencies: [
 .package(path: "../VirtualDisplayKit")
 // Or from a git repository:
 // .package(url: "https://github.com/yourusername/VirtualDisplayKit.git", from: "1.0.0")
]

.target(
 name: "YourApp",
 dependencies: ["VirtualDisplayKit"]
)

Xcode Project

Demo Application

Quick Start

Simple Usage with VirtualDisplayController

import VirtualDisplayKit
// Create a controller
let controller = VirtualDisplayController(preset: .standard1080p)
// Start the virtual display
controller.start()
// Create and show a preview window
let window = controller.createPreviewWindow()
window.makeKeyAndOrderFront(nil)
// When done, stop the display
controller.stop()

SwiftUI Integration

import SwiftUI
import VirtualDisplayKit
struct ContentView: View {
 @StateObject private var virtualDisplay = VirtualDisplay(
 configuration: VirtualDisplayConfiguration(
 name: "My Display",
 maxWidth: 1920,
 maxHeight: 1080
 )
 )
 
 var body: some View {
 VStack {
 VirtualDisplayView(virtualDisplay: virtualDisplay) { point in
 // Handle tap - move cursor to that point
 virtualDisplay.moveCursor(to: point)
 }
 .frame(maxWidth: .infinity, maxHeight: .infinity)
 
 HStack {
 Button("Start") {
 virtualDisplay.start()
 }
 .disabled(virtualDisplay.isReady)
 
 Button("Stop") {
 virtualDisplay.stop()
 }
 .disabled(!virtualDisplay.isReady)
 }
 }
 .padding()
 }
}

Recording

let controller = VirtualDisplayController(preset: .standard1080p)
controller.start()
// Start recording with high quality settings
let outputURL = URL(fileURLWithPath: "/path/to/recording.mp4")
try controller.startRecording(to: outputURL, configuration: .highQuality)
// Later, stop recording
let finalURL = try await controller.stopRecording()
print("Recording saved to: \(finalURL)")

Streaming

let controller = VirtualDisplayController(preset: .standard1080p)
controller.start()
// Start streaming with RTMP-optimized settings
try controller.startStreaming(configuration: .rtmpStreaming) { data, presentationTime, isKeyFrame in
 // Send encoded H.264 data to your streaming server
 // data: Annex B formatted NAL units
 // presentationTime: CMTime for synchronization
 // isKeyFrame: true for I-frames
 
 yourRTMPClient.sendVideoFrame(data, timestamp: presentationTime, isKeyframe: isKeyFrame)
}
// Stop streaming
controller.stopStreaming()

Advanced: Direct Frame Access

let renderer = DisplayStreamRenderer(backend: .cgDisplayStream, showCursor: true)
renderer.configure(displayID: displayID, resolution: resolution, scaleFactor: scaleFactor)
// Get IOSurface frames
renderer.onFrameAvailable = { surface in
 // Use IOSurface for Metal/OpenGL rendering
}
// Get CVPixelBuffer frames (for VideoToolbox, Core Image, etc.)
renderer.onPixelBufferAvailable = { pixelBuffer in
 // Process with Core Image, VideoToolbox, etc.
}

Configuration Options

VirtualDisplayConfiguration

let configuration = VirtualDisplayConfiguration(
 name: "My Virtual Display", // Display name shown in System Preferences
 maxWidth: 3840, // Maximum width in pixels
 maxHeight: 2160, // Maximum height in pixels
 physicalSizeMillimeters: CGSize(width: 600, height: 340), // Physical size for DPI
 vendorID: 0x3456, // Vendor ID for identification
 productID: 0x1234, // Product ID for identification
 serialNumber: 0x0001, // Serial number
 hiDPIEnabled: true, // Enable Retina/HiDPI modes
 refreshRate: 60, // Refresh rate in Hz
 displayModes: [ // Available resolution modes
 DisplayMode(width: 1920, height: 1080, refreshRate: 60),
 DisplayMode(width: 1280, height: 720, refreshRate: 60),
 ],
 showCursor: true, // Show cursor in stream
 streamingBackend: .automatic // Streaming technology to use
)

Configuration Presets

// Standard 1080p
let config1 = VirtualDisplayConfiguration.preset1080p
// 4K resolution
let config2 = VirtualDisplayConfiguration.preset4K
// Digital signage (includes portrait modes)
let config3 = VirtualDisplayConfiguration.presetSignage

Architecture

VirtualDisplayKit/
├── Package.swift # SPM package definition
├── Sources/
│ ├── CVirtualDisplayPrivate/ # C headers for private APIs
│ │ └── include/
│ │ └── CGVirtualDisplayPrivate.h
│ └── VirtualDisplayKit/
│ ├── Core/
│ │ ├── VirtualDisplay.swift # Main display manager
│ │ ├── VirtualDisplayConfiguration.swift
│ │ ├── DisplayStreamRenderer.swift # Stream rendering
│ │ ├── DisplayRecorder.swift # Video recording
│ │ └── FrameOutputStream.swift # Streaming output
│ ├── Views/
│ │ ├── VirtualDisplayView.swift # SwiftUI view
│ │ └── VirtualDisplayNSView.swift # AppKit view
│ ├── VirtualDisplayController.swift # High-level controller
│ └── VirtualDisplayKit.swift # Public exports
├── Tests/
│ └── VirtualDisplayKitTests/
├── VirtualDisplayDemo/ # Demo app source
└── VirtualDisplayDemo.xcodeproj # Demo app project

Use Cases

Digital Signage Testing

let controller = VirtualDisplayController(preset: .signage)
controller.start()
// Your signage app will see this as a real display
// Record a demo video
try controller.startRecording(to: demoURL, configuration: .highQuality)

Multi-Monitor Development

// Create multiple virtual displays
let display1 = VirtualDisplay(configuration: VirtualDisplayConfiguration(name: "Virtual 1"))
let display2 = VirtualDisplay(configuration: VirtualDisplayConfiguration(name: "Virtual 2"))
display1.start()
display2.start()

Streaming Integration

let stream = FrameOutputStream(configuration: .rtmpStreaming)
stream.configure(displaySize: resolution, scaleFactor: 2.0)
stream.onEncodedFrame = { data, time, isKeyFrame in
 // Send to RTMP server
 rtmpClient.publish(data: data, timestamp: time.seconds)
}
try stream.start()

Important Notes

Private API Usage

Permissions

Known Limitations

License

Credits