Playing custom audio with your own player

At a glance

Project structure

SampleBufferPlayer/
├── SampleBufferPlayerApp.swift
├── ContentView.swift
├── General/
│   ├── PlaylistItem.swift
│   ├── RemoteCommandCenter.swift
│   └── NowPlayingCenter.swift
└── Player/
    ├── SampleBufferPlayer.swift
    ├── SampleBufferSerializer.swift
    ├── SampleBufferItem.swift
    └── SampleBufferSource.swift

Structure observations

• SampleBufferPlayer is the application-facing API; lower files form a staged media pipeline.
• Remote commands and Now Playing updates live outside the renderer, keeping system integration separate from buffer production.

Overall architecture

flowchart LR
    View["ContentView"] --> Player["SampleBufferPlayer"]
    Remote["MPRemoteCommandCenter"] --> Adapter["RemoteCommandCenter"]
    Adapter --> Player
    Player --> Serializer["SampleBufferSerializer serial queue"]
    Serializer --> Item["SampleBufferItem"]
    Item --> Source["SampleBufferSource"]
    Source --> File["AVAudioFile"]
    Serializer --> Renderer["AVSampleBufferAudioRenderer"]
    Serializer --> Sync["AVSampleBufferRenderSynchronizer"]
    Player --> Now["NowPlayingCenter"]

Reference code

SampleBufferPlayer/Player/SampleBufferSerializer.swift:40 — nonpublic playback logic and framework renderers are owned by one serial executor.

private let serializationQueue = DispatchQueue(
    label: "sample.buffer.player.serialization.queue")
private let audioRenderer = AVSampleBufferAudioRenderer()
private let renderSynchronizer = AVSampleBufferRenderSynchronizer()
private var items: [SampleBufferItem] = []

Interpretation

The façade owns editable playlist semantics and observable UI values. The serializer owns ordered playback mutations; items own per-play instance state, and sources translate file frames into timestamped CMSampleBuffer values.

Ownership and state

classDiagram
    ContentView *-- SampleBufferPlayer : State owns
    SampleBufferPlayer *-- Playlist : owns under semaphore
    SampleBufferPlayer *-- SampleBufferSerializer : owns
    SampleBufferSerializer *-- AVSampleBufferAudioRenderer : owns
    SampleBufferSerializer *-- AVSampleBufferRenderSynchronizer : owns
    SampleBufferSerializer *-- SampleBufferItem : queue owns
    SampleBufferItem *-- SampleBufferSource : lazy owns
    RemoteCommandCenter o-- RemoteCommandHandler : weak capture

Ownership evidence

SampleBufferPlayer/ContentView.swift:13 — the root view creates the long-lived observable façade.

struct ContentView: View {
    @State private var sampleBufferPlayer = SampleBufferPlayer()
    @State private var editMode = EditMode.inactive
}

Class and protocol design

Access control

Reference code

SampleBufferPlayer/Player/SampleBufferPlayer.swift:21 — mutable playlist truth is hidden behind the façade and semaphore.

private struct Playlist {
    var items: [SampleBufferItem] = []
    var currentIndex: Int?
}
private let atomicitySemaphore = DispatchSemaphore(value: 1)
private var playlist = Playlist()
private var playbackSerializer: SampleBufferSerializer!

Logic ownership and placement

Design patterns

Naming conventions

• The shared SampleBuffer prefix connects façade, serializer, item, and source layers.
• Role suffixes state responsibility: Player, Serializer, Item, Source, Center.
• Queue commands distinguish replacement from continuity: restartQueue and continueQueue.
• Mutation methods use playlist verbs: insertItem, removeItem, moveItems, replaceItems.

Architecture takeaways

• Separate editable playlist policy from serialized rendering mechanics.
• Make queue ownership and execution context explicit when framework renderers are stateful.
• Use wrapper items for per-play identity even when the underlying playlist model can repeat.
• Keep remote commands and Now Playing publication as adapters around the core player.
• Read-only setters expose useful status without surrendering mutation authority.

Source map

• Official Apple documentation