Integrating your music app with Apple Intelligence

At a glance

Project structure

CosmoTunes/
├── AppIntents/
│   ├── Audio/                  # Entities, queries, playback/share intents
│   ├── Clock/                  # Alarm and timer contracts
│   └── TestSupport/
├── Managers/                  # Data, playback, indexing, alarms, rendering
├── Model/                     # SwiftData and ActivityKit values
├── Views/                     # Chat, library, player, alarms, settings
└── CosmoTunesApp.swift        # Composition root
CosmoTunesWidget/              # Widget and Live Activity target
CosmoTunesUITests/             # Entity, intent, Spotlight, UI tests

The sample is code-rich, but its top-level organization is consistent: domain contracts under AppIntents, durable values under Model, long-lived capabilities under Managers, and target-specific presentation under app or widget folders.

Overall architecture

flowchart LR
    Root["CosmoTunesApp"] --> Views["SwiftUI views"]
    Root --> Data["ModelManager / SwiftData"]
    Root --> Playback["PlaybackController"]
    Playback --> Engine["AudioEngine / AVFoundation"]
    Root --> Session["CosmoTunesMediaSession / NowPlaying"]
    Playback <--> Session
    Root --> Time["Timer + Alarm managers"]
    Root --> DI["AppDependencyManager"]
    DI --> Intents["Audio and Clock intents"]
    Intents --> Data
    Intents --> Playback
    Widget["CosmoTunesWidgetExtension"] --> Live["WidgetKit / ActivityKit"]

Reference code

CosmoTunes/CosmoTunesApp.swift:92 — the composition root exposes selected managers to all intent and query invocations.

AppDependencyManager.shared.add(dependency: navigation)
AppDependencyManager.shared.add(dependency: playback)
AppDependencyManager.shared.add(dependency: timerController)
AppDependencyManager.shared.add(dependency: model)
AppDependencyManager.shared.add(dependency: donations)
AppDependencyManager.shared.add(dependency: alarmScheduler)
AppDependencyManager.shared.add(dependency: userPreferences)

The root performs wiring, while each manager keeps one operational concern. The widget is a separate executable boundary and consumes shared ActivityKit values rather than the app’s live manager graph.

Ownership and state

classDiagram
    CosmoTunesApp *-- ModelManager : strong owner
    CosmoTunesApp *-- PlaybackController : strong owner
    CosmoTunesApp *-- CosmoTunesMediaSession : strong owner
    CosmoTunesApp *-- TimerController : strong owner
    PlaybackController *-- AudioEngine : creates
    PlaybackController o-- CosmoTunesMediaSession : weak
    CosmoTunesMediaSession o-- PlaybackController : weak
    ModelManager *-- SpotlightIndexer : owns
    ModelManager o-- TrackAudioRenderer : weak
    PlayAudioIntent --> ModelManager : injected
    PlayAudioIntent --> PlaybackController : injected

Ownership evidence

CosmoTunes/CosmoTunesApp.swift:56 — the root wires non-owning cross-links after creating every long-lived manager.

playback.donations = donations
playback.audioEngine.mediaSession = mediaSession
playback.mediaSession = mediaSession
mediaSession.playback = playback
mediaSession.artworkRenderer = artworkRenderer

Class and protocol design

This sample combines framework protocol conformances with one purposeful app-defined seam: SpotlightWrapping is injected into SpotlightIndexer, while concrete playback managers remain directly composed.

Access control

Reference code

CosmoTunes/Managers/PlaybackController.swift:30 — readable playback snapshots have a single mutation owner.

private(set) var currentTrackNotes: [MIDINoteData] = []
private(set) var playQueue: [GeneratedTrack] = []
private(set) var queueIndex = 0
private(set) var currentPlaylist: Playlist?

weak var donations: DonationManager?
weak var mediaSession: CosmoTunesMediaSession?

Logic ownership and placement

Design patterns

Naming conventions

• Long-lived capabilities use role suffixes: Manager, Controller, Engine, Renderer, Indexer, and Session.
• Framework projections use Entity; framework actions use verb-noun Intent names.
• Methods describe commands at the correct layer: playTracks, loadAndPlay, publishSnapshot, and performChange.
• Read-only state names describe snapshots (currentTrackNotes, playQueue, playbackSnapshot).
• Files match primary types, while extensions group protocol conformances such as EntityQuery, Transferable, and MediaSessionRepresentable.

Architecture takeaways

• Keep a large sample understandable by assigning state to narrowly named subsystem owners and doing all cross-wiring at the app root.
• Put queue policy above the AVFoundation engine and expose read-only snapshots with private(set).
• Use weak links where two coordinators need to call each other, while one root strongly owns both.
• Share immutable ActivityKit payload types with the widget; do not attempt to share the app’s live dependency graph across targets.
• Add a custom protocol only where replacement materially improves testing, as with Spotlight I/O.

Source map

• Official Apple documentation