webrtc-macos-scaffold

Native macOS WebRTC streaming scaffold · Swift 6 strict concurrency · MVI architecture · Metal zero-copy rendering.

Overview

A reusable architectural scaffold for native macOS clients that consume a low-latency video stream over WebRTC. The scaffold demonstrates four invariants that are hard to retrofit after the fact:

1. Swift 6 strict concurrency end-to-end. No nonisolated(unsafe) shortcuts. The compiler is the witness.
2. Unidirectional MVI. A single @MainActor-isolated store. State is read-only; mutation only via dispatched intents.
3. Sendable boundaries at every cross-actor seam — including the C-thread → @MainActor boundary the WebRTC track produces against.
4. Zero-copy Metal rendering. Decoded CVPixelBuffer frames cross into Metal via CVMetalTextureCache without CPU copies.

Architecture

flowchart TD
    A[StreamingNetwork: WebRTC track] -->|raw byte samples cross Sendable boundary| B(MediaPipeline: VTDecompressionSession)
    B -->|hardware decode| C{frame dropped?}
    C -->|yes| D[log frame churn]
    C -->|no| E[emit Intent: frameDecoded]
    E -->|route to @MainActor| F[Store: mutate render state]
    F --> G[Renderer: CVMetalTextureCache]
    G -->|zero-copy| H[Metal shader engine]
    H --> I[MTKView: present drawable]

Loading

Modules

Package	Responsibility
StreamingAuth	OAuth-delegated authentication via ASWebAuthenticationSession + Keychain
StreamingNetwork	WebRTC media engine, SDP signaling protocol seam, QoS tagging
MediaPipeline	Hardware H.264 / HEVC decode bridge (VTDecompressionSession)
Renderer	MTKView + CVMetalTextureCache zero-copy render pipeline
StreamingLogging	os.Logger subsystem with bounded ring buffer

Tech stack

• Swift 6 strict concurrency — eliminates data races at compile time across the high-frequency C-thread / @MainActor boundary
• MVI — single source of truth on @MainActor, intents are explicit, no bidirectional bindings
• Metal 3 + CVMetalTextureCache — zero-copy GPU rendering; no CPU memory copies in the render loop
• VideoToolbox — hardware H.264 / HEVC decode on Apple Silicon
• WebRTC (stasel/WebRTC 125) — DTLS-over-UDP tunnel for the media path
• ASWebAuthenticationSession — out-of-process OAuth (no embedded WebView, no token passing through the app process)
• macOS Keychain (Security.framework) — encrypted token persistence

Quickstart

git clone https://github.com/jcellomarcano/webrtc-macos-scaffold.git
cd webrtc-macos-scaffold
swift build
swift test

Requires Swift 6.0+, macOS 14+, Apple Silicon for the hardware decode + Metal paths.

To open in Xcode for live development:

open Package.swift

Using the scaffold

The scaffold ships stubs for the signaling client and the decode / render bridges. Integrators replace:

• Packages/StreamingNetwork/Sources/StreamingNetwork/Internal/SignalingClient.swift — implement the operator's WebRTC signaling protocol.
• Packages/MediaPipeline/Sources/MediaPipeline/MediaPipeline.swift — wire VTDecompressionSession for the operator's wire format.
• Packages/Renderer/Sources/Renderer/Renderer.swift — extend with the operator's render passes (shaders, color conversion, etc.).
• Packages/StreamingAuth/Sources/StreamingAuth/AuthFactory.swift — replace the placeholder OAuth endpoint with the operator's authorization URL.

Disclaimer

This is an independent open-source scaffold. Not affiliated with, endorsed by, or sponsored by any commercial cloud-streaming or cloud-gaming provider. Mentions of WebRTC, OAuth 2.0, Metal, VideoToolbox, and related technologies refer to the public, well-documented standards and frameworks. The scaffold does not implement any vendor-specific protocol; integrators provide their own signaling and decoding behavior. All third-party trademarks remain the property of their respective owners.

License

MIT — © 2026 Parallel Digital LLC and contributors.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and METHODOLOGY.md.

Authors

Operated by Parallel Digital LLC — open source contribution by Jesús Marcano · jesus@paralleldigital.com