Building an audio sequencer to arrange and play clips

At a glance

Project structure

ClipLauncher/ClipLauncher/
├── ClipLauncherApp.swift
├── Views/
│   ├── ContentView.swift
│   ├── Grid/
│   └── Controls/
├── ViewModel/ClipLauncherViewModel.swift
├── Controller/ClipLauncherController.swift
├── Models/{AudioClip,ClipTrack,ClipScene}.swift
└── Audio/
    ├── ClipEngine.swift
    ├── ClipEngine+Playback.swift
    ├── ClipEngine+Transport.swift
    ├── ClipEngine+Synchronization.swift
    ├── ClipEngine+Metering.swift
    └── ClipLoader.swift

Structure observations

• Folder names describe architectural layers; small UI controls are further grouped by role.
• ClipEngine stores shared engine state while same-type extensions separate playback, transport, synchronization, and metering.

Overall architecture

flowchart LR
    Views["SwiftUI views"] --> VM["ClipLauncherViewModel"]
    VM --> Controller["ClipLauncherController"]
    Controller --> Loader["ClipLoader actor"]
    Controller --> Engine["ClipEngine @MainActor"]
    Loader --> Model["AudioClip Sendable"]
    Model --> Engine
    Engine --> Graph["Player → Varispeed → Track mixer → Main mixer"]
    Controller -. AsyncStream events .-> VM

Reference code

ClipLauncher/ClipLauncher/Controller/ClipLauncherController.swift:125 — the controller crosses the loader boundary, updates the engine, then emits a UI event.

func loadClip(from url: URL, into trackID: ClipEngine.TrackID, sceneID: UUID) async {
    do {
        let result = try await loader.load(from: url)
        engine.ensureTrack(trackID)
        engine.loadClip(result.clip, into: trackID)
        emit(.clipLoaded(trackID: trackID, sceneID: sceneID, clip: result.clip))
    } catch {
        emit(.clipLoadFailed(trackID: trackID, sceneID: sceneID, error: error.localizedDescription))
    }
}

Interpretation

The view model owns presentation state and exposes user actions. The controller coordinates cross-component operations. File I/O and analysis are isolated in an actor; graph mutation remains on the main actor.

Ownership and state

classDiagram
    ContentView *-- ClipLauncherViewModel : State owns
    ClipLauncherViewModel *-- ClipLauncherController : owns
    ClipLauncherController *-- ClipLoader : owns
    ClipLauncherController *-- ClipEngine : owns
    ClipEngine *-- AVAudioEngine : owns
    ClipEngine *-- LoadedClip : retains per track
    ClipLauncherViewModel *-- ClipTrack : UI state

Ownership evidence

ClipLauncher/ClipLauncher/ViewModel/ClipLauncherViewModel.swift:52 — the view model owns UI state while hiding its controller and tasks.

private(set) var tracks: [ClipTrack] = []
private(set) var mainTempo: Double = Constants.BPM.defaultTempo
@ObservationIgnored private let controller = ClipLauncherController()
@ObservationIgnored private var eventTask: Task<Void, Never>?

Class and protocol design

The main abstraction boundary is actor isolation and the controller API; the sample does not introduce an app-defined service protocol.

Access control

Reference code

ClipLauncher/ClipLauncher/Audio/ClipEngine.swift:38 — engine internals deliberately remain module-visible for cross-file extensions.

// MARK: - Internal Implementation
let engine = AVAudioEngine()
let mixer: AVAudioMixerNode
var trackMixers: [TrackID: AVAudioMixerNode] = [:]
var clips: [TrackID: [UUID: LoadedClip]] = [:]
var launchQueue: [TrackID: AudioClip] = [:]

Logic ownership and placement

Design patterns

Main application flow

sequenceDiagram
    actor User
    participant VM as ViewModel
    participant C as Controller
    participant E as ClipEngine
    User->>VM: Launch scene
    loop each populated track
        VM->>C: queueClip(track, clipID)
        C->>E: queue clip
    end
    VM->>C: flushLaunchQueue()
    C->>E: schedule common quantized start
    E-->>C: launch callbacks
    C-->>VM: AsyncStream clipStarted events

Reference code

ClipLauncher/ClipLauncher/ViewModel/ClipLauncherViewModel.swift:228 — scene launch batches commands before one synchronized flush.

for tIndex in tracks.indices {
    guard let clip = tracks[tIndex].scenes[sceneIndex].clip else { continue }
    try? controller.queueClip(track: tracks[tIndex].id, clipID: clip.id)
}
controller.flushLaunchQueue()

Naming conventions

• Layer roles appear as suffixes: View, ViewModel, Controller, Engine, Loader.
• Commands use direct verbs: importClip, queueClip, flushLaunchQueue, stopAll.
• State names use domain language: ClipTrack, ClipScene, launchQueue, beatCounter.
• Engine extension filenames name their behavior: +Playback, +Transport, +Synchronization, +Metering.

Architecture takeaways

• Give observable UI state, orchestration, I/O, and graph mutation distinct owners.
• Use a typed event stream when lower layers must report asynchronous domain events upward.
• Keep a single actor in charge of AVAudioEngine graph state while moving file analysis to another actor.
• Cross-file extensions can justify internal engine state; document that boundary rather than marking everything private.
• Batch scene commands, then commit once, when synchronization is the business invariant.

Source map

• Official Apple documentation