Synchronizing custom video playback with SharePlay

At a glance

Project structure

SyncCustomVideoPlaybackWithSharePlay/
├── SyncCustomVideoPlaybackWithSharePlay.xcodeproj/
└── SyncCustomVideoPlaybackWithSharePlay/
    ├── SyncCustomVideoPlaybackWithSharePlayApp.swift  // scenes + injection
    ├── AppModel.swift                                 // immersive state + session owner
    ├── GroupActivities/
    │   ├── SyncCustomVideoPlaybackActivity.swift      // GroupActivity value
    │   └── PlaybackSessionController.swift            // session lifecycle, UI facade
    ├── PlaybackEngine/
    │   ├── PlaybackCoordinator.swift                  // AV coordinator + delegate → stream
    │   ├── PlaybackRenderer.swift                     // synchronizer, VideoMaterial, pump actor
    │   └── VideoSampleSource.swift                    // asset, duration, reader factory
    ├── Views/
    │   ├── ContentView.swift / ToggleImmersiveSpaceButton.swift
    │   ├── ImmersiveView.swift                        // RealityView blob + attachment
    │   └── PlaybackPanelView.swift                    // transport controls
    ├── Extension/  Logger.swift, MeshResource+Blob.swift
    └── SyncCustomVideoPlaybackWithSharePlay.entitlements

Structure observations

• The folders follow the data flow. GroupActivities/ holds SharePlay session concerns. PlaybackEngine/ holds the media pipeline, which knows nothing about views. Views/ reads state and sends commands back through one controller.
• PlaybackRenderer.swift holds two types: the @MainActor renderer and the VideoSamplePump actor it owns (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:14, SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:167). The pump is an implementation detail of rendering and lives in the same file.
• Extensions use the Type+Feature file name (MeshResource+Blob.swift). Logger.swift centralizes the logging subsystem so the subsystem string “can’t drift” (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/Extension/Logger.swift:11).
• The target opts into SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor with Swift 6 (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay.xcodeproj/project.pbxproj:180). This is why the source spells out nonisolated exceptions rather than @MainActor everywhere.

Overall architecture

flowchart LR
    App["SyncCustomVideoPlaybackWithSharePlayApp"] --> Model["AppModel"]
    Model --> Controller["PlaybackSessionController"]
    Views["ContentView / PlaybackPanelView / ImmersiveView"] -->|play, pause, seek, startSharePlay| Controller
    Controller -->|for await sessions()| GS["GroupSession"]
    Controller --> Coord["PlaybackCoordinator"]
    Coord -->|AsyncStream of Command| Renderer["PlaybackRenderer"]
    Renderer --> Pump["VideoSamplePump actor"]
    Pump --> Source["VideoSampleSource"]
    Renderer -->|VideoMaterial| Views

Reference code

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/GroupActivities/PlaybackSessionController.swift:123 — makePlayback(videoName:videoExtension:) wires one renderer to one coordinator

private func makePlayback(videoName: String, videoExtension: String) async
    -> (renderer: PlaybackRenderer, coordinator: PlaybackCoordinator)? {
    guard let url = Bundle.main.url(forResource: videoName, withExtension: videoExtension) else { return nil }
    // Create new render and coordination pipelines.
    let newSampleSource = VideoSampleSource(url: url)
    let newRenderer = await PlaybackRenderer(sampleSource: newSampleSource)
    let newCoordinator = PlaybackCoordinator()

    // Wire commands of the coordinator to the renderer.
    newRenderer.drain(commands: newCoordinator.commands)
    newRenderer.pauseCoordinatorOnEnd = { [weak newCoordinator] in newCoordinator?.coordinatePause() }

    return (newRenderer, newCoordinator)
}

Interpretation

Observation: the sample has two pipelines with one-way links between them. Local intent goes out through PlaybackCoordinator.coordinatePlay/Pause/Seek, and nothing touches the synchronizer on that path. The group’s decision comes back as a Command on an AsyncStream, and only PlaybackRenderer applies it. PlaybackSessionController is the composition point. It creates both halves per session and connects them with exactly two links: the command stream, and a weakly captured end-of-media callback.

Inference: routing even a local tap through the group coordinator means every participant, including the one who tapped, applies the same timed command. That keeps playback consistent and avoids a separate “local fast path”.

Ownership and state

classDiagram
    SyncCustomVideoPlaybackWithSharePlayApp *-- AppModel : @State
    AppModel *-- PlaybackSessionController : let session
    PlaybackSessionController *-- PlaybackRenderer : private(set), per session
    PlaybackSessionController *-- PlaybackCoordinator : private, per session
    PlaybackSessionController o-- GroupSession : private(set), received
    PlaybackCoordinator *-- PlaybackControlDelegate : strong let
    PlaybackRenderer *-- VideoSamplePump : let pump
    VideoSamplePump o-- VideoSampleSource : injected
    PlaybackPanelView --> PlaybackSessionController : let session (init-injected)
    ImmersiveView --> AppModel : @Environment

Ownership evidence

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/AppModel.swift:10 — AppModel

@MainActor
@Observable
class AppModel {
    let immersiveSpaceID = "ImmersiveSpace"
    // ...
    var immersiveSpaceState = ImmersiveSpaceState.closed

    // The SharePlay listener for the app's lifetime.
    let session = PlaybackSessionController()
}

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/GroupActivities/PlaybackSessionController.swift:117 — resetSession() is the single teardown point

private func resetSession() {
    groupSession = nil
    playbackRenderer = nil
    playbackCoordinator = nil
}

Notes:

• The renderer does not own the coordinator. pauseCoordinatorOnEnd captures it with [weak newCoordinator] (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/GroupActivities/PlaybackSessionController.swift:133), so clearing playbackCoordinator in resetSession() is enough to release it.
• Teardown chain (observation): resetSession() releases the coordinator. Its isolated deinit calls continuation.finish() (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackCoordinator.swift:36-38). That ends the renderer’s for await command in commands loop (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:81). The renderer’s own isolated deinit removes the time observer and cancels drainTask and statusTask (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:57-63).
• Inference: PlaybackCoordinator keeps the delegate in a strong let because the AV coordinator is not shown to retain it. Without that property, nothing in the sample would keep the delegate alive.

Concurrency, scheduling, and thread safety

Evidence limit: actor isolation, async/await, or Task creation does not by itself prove background-thread execution; Sendable conformance alone does not prove thread-safe mutation.

Default isolation matters here. The target compiles with SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay.xcodeproj/project.pbxproj:180). Unannotated views and helpers are therefore main-actor isolated. The source opts out explicitly with nonisolated on the GroupActivity value (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/GroupActivities/SyncCustomVideoPlaybackActivity.swift:11), the AV delegate class (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackCoordinator.swift:72), static loggers, and the Logger initializer (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/Extension/Logger.swift:18).

Command is declared Sendable and every completion handler is @Sendable (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackCoordinator.swift:64-69). That is a transfer contract across the delegate-to-renderer boundary, not a lock. Serialization comes from the single drainTask consumer.

Inference on lifetime: inside the listener and monitor tasks, await self?.listen() evaluates self once for the whole call. While that loop runs, the controller stays referenced, so isolated deinit cancellation would matter only after the loop exits. The AppModel comment declares an app-lifetime listener anyway (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/AppModel.swift:21). The drain and status loops re-check self? on each element instead.

Reference code

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:188 — VideoSamplePump.start(at:)

func start(at time: CMTime) async -> AsyncStream<SampleSourceStatus> {
    // Replace any existing supply.
    renderTask?.cancel()
    _ = await renderTask?.value
    receiver.flush()

    return AsyncStream { continuation in
        renderTask = Task(name: "render", priority: .userInitiated) { [self] in
            defer { renderTask = nil; continuation.finish() }
            do {
                var (reader, provider) = try await sampleSource.makeReaderAndProvider(at: time)
                defer { reader.cancelReading() }
                while !Task.isCancelled, let sample = try await provider.next() {
                    // ...
                }
                continuation.yield(Task.isCancelled ? .suspended : .finished)
            } catch is CancellationError {
                continuation.yield(.suspended)
            } catch {
                continuation.yield(.failed(error))
            }
        }
    }
}

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/GroupActivities/PlaybackSessionController.swift:53 — listener task ownership

init() {
    self.listenTask = Task { @MainActor [weak self] in
        await self?.listen()
    }
}
isolated deinit {
    listenTask?.cancel()
    stateMonitorTask?.cancel()
}

State propagation, frameworks, and dependencies

Evidence limit: an import proves a source-level compilation dependency at the cited line; it does not prove runtime use, architectural adoption, or whether a Swift package is a direct application dependency.

No Swift package manifest or package reference is part of the tree.

Class and protocol design

classDiagram
    class AVPlaybackCoordinatorPlaybackControlDelegate {
        <<protocol>>
    }
    class Command {
        <<enum>>
        play
        pause
        seek
        buffer
    }
    PlaybackControlDelegate ..|> AVPlaybackCoordinatorPlaybackControlDelegate
    PlaybackCoordinator *-- PlaybackControlDelegate
    PlaybackControlDelegate --> Command : yields
    PlaybackRenderer --> Command : drains
    SyncCustomVideoPlaybackActivity ..|> GroupActivity
    SyncCustomVideoPlaybackActivity ..|> Transferable

Reference code

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackCoordinator.swift:72 — PlaybackControlDelegate

private nonisolated final class PlaybackControlDelegate: NSObject, AVPlaybackCoordinatorPlaybackControlDelegate {
    private let continuation: AsyncStream<Command>.Continuation
    // ...
    func playbackCoordinator(
        _ coordinator: AVDelegatingPlaybackCoordinator,
        didIssue pauseCommand: AVDelegatingPlaybackCoordinatorPauseCommand,
        completionHandler: @escaping @Sendable () -> Void
    ) {
        dispatch(.pause(completionHandler: completionHandler))
    }
    // ...
}

No app-defined protocol exists. The only protocol boundary is AVFoundation’s delegate protocol, adopted by a file-private class.

Access control

Reference code

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:14 — renderer state surface

final class PlaybackRenderer {
    // ...
    let videoMaterial: VideoMaterial
    private let synchronizer: AVSampleBufferRenderSynchronizer
    private let pump: VideoSamplePump

    let durationSeconds: Double?
    private(set) var currentSeconds: Double? = nil
    private(set) var isPlaying: Bool = false
    // ...
}

Logic ownership and placement

Design patterns

Not claimed:

• PlaybackCoordinator is named after AVDelegatingPlaybackCoordinator. It does not coordinate navigation or app flow, so it is not labeled a Coordinator pattern.
• Command is a message enum that the renderer interprets, not an object that executes itself, so it is not labeled the Command pattern.
• No MVVM is claimed. No type is a per-view model.

Main application flow

sequenceDiagram
    actor User
    participant Panel as PlaybackPanelView
    participant Ctrl as PlaybackSessionController
    participant Coord as PlaybackCoordinator
    participant Del as PlaybackControlDelegate
    participant Rend as PlaybackRenderer
    User->>Panel: Tap Play
    Panel->>Ctrl: play()
    Ctrl->>Coord: coordinatePlay()
    Coord->>Coord: coordinateRateChange(to: 1)
    Del-->>Rend: yield .play(rate, time, atHostTime)
    Rend->>Rend: handle → applyPlay → setRate(atHostTime)
    Rend-->>Del: completionHandler()

Reference code

SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:78 — inbound drain and serial apply

    func drain(commands: AsyncStream<Command>) {
        self.drainTask?.cancel()
        self.drainTask = Task { @MainActor [weak self] in
            for await command in commands {
                await self?.handle(command)
            }
        }
    }

    private func handle(_ command: Command) async {
        switch command {
        case let .play(rate, time, atHostTime, completionHandler):
            await applyPlay(rate: rate, time: time, atHostTime: atHostTime)
            completionHandler()
        // ...
        case let .buffer(completionHandler):
            await applyBuffering()
            completionHandler()
        }
    }

The local tap never sets the synchronizer rate directly. It reaches setRate only after the AV coordinator issues a play command to the delegate (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackCoordinator.swift:92-103).

Naming conventions

• Types: role suffixes match responsibilities in source. …Controller owns the session lifecycle. …Coordinator wraps the AV playback coordinator. …Renderer owns the synchronizer and material. …Source produces readers. …Pump pushes samples. …Activity is the GroupActivity. …Delegate adopts the AV delegate protocol.
• Direction-named methods: outbound calls are coordinatePlay/Pause/Seek under // MARK: - Outbound Coordination. Inbound calls are applyPlay/Pause/Seek/Buffering under // MARK: - Inbound Coordination. Log prefixes [outbound], [apply], [session], and [activation] mirror the split (SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackCoordinator.swift:45, SyncCustomVideoPlaybackWithSharePlay/SyncCustomVideoPlaybackWithSharePlay/PlaybackEngine/PlaybackRenderer.swift:75).
• Lifecycle methods: listen, monitorSessionState, resetSession, makePlayback (factory-style make prefix), drain(commands:), observeStatus(_:), awaitDuration().
• State names: immersiveSpaceState with closed/inTransition/open. renderStatus: SampleSourceStatus. Boolean isPlaying and isDecoding.
• Files: one primary type per file, except the pump inside PlaybackRenderer.swift. Extensions use MeshResource+Blob.swift.

Architecture takeaways

• Separate outbound intent from inbound application. Local taps only ask the group coordinator. One serial consumer applies the group’s timed commands to the synchronizer, so every participant runs the same path.
• Bridge callback APIs into one AsyncStream and drain it from a single stored task. This gives ordering and a clear place to call completion handlers, including when the stream is already terminated.
• Build per-session pipelines and tear them down by dropping references. resetSession() → coordinator deinit → continuation.finish() → drain loop ends. Weak capture keeps the renderer from extending the coordinator’s lifetime.
• Store every long-running Task in the owner that cancels it (listenTask, stateMonitorTask, drainTask, statusTask, durationTask, renderTask). Cancel the previous one before replacing it.
• Read actor annotations precisely. @MainActor plus SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor keeps most code on the main actor. The only separate isolation domain is the VideoSamplePump actor, and a comment saying “background” does not make a @MainActor task run off-main.

Source map

• Official Apple documentation