Media
You MUST use this skill for ANY camera, photo, audio, haptic, or media playback work.
Auditors are skills here. Where this router says "Launch some-auditor agent", invoke the
matching Codex skill instead — same procedure, no Claude Code agent required.
Available: axiom-audit-camera.
The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run.
Quick Reference
| Symptom / Task |
Reference |
| Camera capture, AVCaptureSession |
See skills/camera-capture.md |
Slow camera launch / deferred start (iOS 26+), ProRes recording via Pro Video Storage (OS27) |
See skills/camera-capture.md Patterns 8-9 |
| Camera API (RotationCoordinator, etc.) |
See skills/camera-capture-ref.md |
| Center Stage front camera (iPhone 17), dynamic aspect ratio, smart framing, 24/48 MP capture |
See skills/camera-capture-ref.md |
| Camera freezes, black preview, rotation |
See skills/camera-capture-diag.md |
| Photo pickers, library access |
See skills/photo-library.md |
| PHPicker, PhotosPicker API reference |
See skills/photo-library-ref.md |
PhotoKit + Swift 6 strict concurrency, nonisolated observer, performChanges isolation, _dispatch_assert_queue_fail |
See axiom-concurrency (skills/isolation-inheritance-diag.md) |
| Audio, AVFoundation, spatial audio |
See skills/avfoundation-ref.md |
Video write/export/playback, sample-buffer engine, resumable export, Apple Log 2, iOS 27 deprecations (OS27) |
See skills/avfoundation-video-ref.md |
| Audio recognition, ShazamKit |
See skills/shazamkit.md |
| ShazamKit API reference |
See skills/shazamkit-ref.md |
On-device music analysis (key, tempo, structure, loudness), MusicUnderstanding (OS27) |
See skills/music-understanding.md |
On-device face grouping (cluster faces into people across a library), video highlights/key frames, MediaIntelligence (OS27) |
See skills/media-intelligence.md |
| Haptic feedback, Core Haptics |
See skills/haptics.md |
| SharePlay coordinated playback, AVDelegatingPlaybackCoordinator, custom-engine sync |
See skills/shareplay-playback.md |
| SharePlay session lifecycle, activation, non-media state |
Use axiom-integration (skills/shareplay.md) instead |
| Now Playing metadata, remote commands |
See skills/now-playing.md |
| Animated lock-screen artwork (iOS 26+) |
See skills/now-playing.md Pattern 8 |
NowPlaying framework (import NowPlaying, Swift-native MediaSession, OS27) |
See skills/now-playing.md (NowPlaying Framework section) |
Cast / route media to non-AirPlay devices (Google Cast/Chromecast, DLNA) as system routes, AVSystemRouting (iOS27, EU-gated/beta) |
See skills/system-media-routing.md |
Screen capture / recording / streaming the screen or your own app, ScreenCaptureKit (OS27 — new on iOS/iPadOS/tvOS/visionOS 27; macOS 12.3+) |
See skills/screen-capture.md |
| CarPlay HIG, app categories, design rules, entitlements |
See skills/carplay-hig.md |
| CarPlay templates reference (all 12 templates, availability matrix, depth limits) |
See skills/carplay-templates-ref.md |
| CarPlay navigation reference (base view, route guidance, cluster/HUD, multitouch, voice prompts, map panels + EV charging iOS 27) |
See skills/carplay-navigation-ref.md |
| CarPlay Now Playing template customization + sports mode |
See skills/now-playing-carplay.md |
| MusicKit Now Playing, ApplicationMusicPlayer playback, subscription/authorization |
See skills/now-playing-musickit.md |
Enumerate the user's Apple Music library — MusicLibraryRequest vs MPMediaQuery, reconciling the two, playlist entries, sync, library identity, per-device Song.id, missing PlayParameters, MusicKit bulk-property pool starvation |
See skills/music-library.md |
| DockKit motorized stands / gimbals, subject tracking, custom motor control |
See skills/dockkit.md |
| Speech-to-text / transcription (SpeechAnalyzer, mic → transcript) |
Invoke axiom-ai (skills/ios-ml.md) |
Decision Tree
digraph media {
start [label="Media task" shape=ellipse];
what [label="Which media feature?" shape=diamond];
start -> what;
what -> "skills/camera-capture.md" [label="camera capture"];
what -> "skills/photo-library.md" [label="photo pickers\n/ library"];
what -> "skills/avfoundation-ref.md" [label="audio / AVFoundation"];
what -> "skills/avfoundation-video-ref.md" [label="video write/export\n/ sample-buffer (OS27)"];
what -> "skills/shazamkit.md" [label="ShazamKit\n/ audio recognition"];
what -> "skills/music-understanding.md" [label="music analysis\n(key/tempo/structure)"];
what -> "skills/media-intelligence.md" [label="face grouping /\nvideo highlights (OS27)"];
what -> "skills/haptics.md" [label="haptic feedback"];
what -> "skills/now-playing.md" [label="Now Playing\n/ remote commands"];
what -> "skills/music-library.md" [label="enumerate Apple Music\nlibrary / identity"];
what -> "skills/system-media-routing.md" [label="cast to non-AirPlay\n(Chromecast/DLNA, iOS27)"];
what -> "skills/screen-capture.md" [label="screen capture /\nrecording (OS27)"];
what -> "skills/carplay-hig.md" [label="CarPlay app design\n/ categories / entitlements"];
what -> "skills/dockkit.md" [label="DockKit stands\n/ gimbals / tracking"];
}
- Camera capture? →
skills/camera-capture.md (patterns), skills/camera-capture-ref.md (API), skills/camera-capture-diag.md (debugging)
- Photo pickers / library? →
skills/photo-library.md, skills/photo-library-ref.md
- Audio / AVFoundation (audio)? →
skills/avfoundation-ref.md; video write/export/playback, sample-buffer engine, resumable export, iOS 27 deprecations? → skills/avfoundation-video-ref.md (OS27)
- ShazamKit / audio recognition? →
skills/shazamkit.md, skills/shazamkit-ref.md
- On-device music analysis (key, tempo, structure, pace, instruments, loudness)? →
skills/music-understanding.md (OS27)
- On-device face grouping (cluster faces into people across a library) or video highlights / key-frame detection? →
skills/media-intelligence.md (OS27)
- Haptics? →
skills/haptics.md
- Now Playing / remote commands? →
skills/now-playing.md, skills/now-playing-carplay.md, skills/now-playing-musickit.md
- Reading the user's Apple Music library (enumerate songs/playlists, library identity, sync)? →
skills/music-library.md — a different problem from playback; read it before any library walk
- Cast / route media to non-AirPlay devices (Google Cast/Chromecast, DLNA) as system routes? →
skills/system-media-routing.md (iOS27, EU-gated/beta)
- Screen capture / recording / streaming the screen or your own app (ScreenCaptureKit)? →
skills/screen-capture.md (OS27 — new on iOS/iPadOS/tvOS/visionOS 27)
- CarPlay app design, category selection, entitlement request? →
skills/carplay-hig.md (start here for any CarPlay work)
- DockKit motorized stands / gimbals, subject tracking, custom motor control? →
skills/dockkit.md
- Want camera code audit? →
axiom-audit-camera (detects deprecated APIs and architectural gaps: missing interruption handlers, runtime-error recovery, audio session deactivation, permission-denied UX, RotationCoordinator on iOS 17+; scores RELIABLE / FRAGILE / BROKEN)
Cross-Domain Routing
Camera + permissions (camera access denied, Info.plist missing):
- Camera code → stay here (camera-capture)
- Privacy manifest / Info.plist → invoke axiom-integration (privacy-ux reference)
- Build/entitlement errors → invoke axiom-build
ShazamKit + microphone permissions:
- Microphone NSMicrophoneUsageDescription → invoke axiom-integration (privacy-ux reference)
- ShazamKit API and matching → stay here (shazamkit)
Now Playing + background audio:
- Now Playing metadata/controls → stay here (now-playing)
- Background audio mode / BGTaskScheduler → invoke axiom-integration (background-processing reference)
Speech-to-text + audio capture (transcribing mic or asset audio):
SpeechAnalyzer / SpeechTranscriber, the ~2-simultaneous-analyzer cap, the OS27 input providers → invoke axiom-ai (skills/ios-ml.md)- Audio session category/mode,
AVCaptureSession wiring → stay here (avfoundation-ref, camera-capture)
- The trap:
CaptureInputSequenceProvider.providerWithSession(...) (OS27) automatically reconfigures your app's default AVAudioSession. If this suite's audio-session setup "randomly breaks" after transcription is added, that's the cause — use provider(from:in:) and add its captureAudioDataOutput to your own session.
Apple Music library + playback + persistence:
- Enumerating the library, library identity,
PlayParameters availability, Sync Library hazards → stay here (music-library)
- Queuing and playing what you found, Now Playing publishing → stay here (now-playing-musickit)
- Storing library rows in your own database (which column is the durable key, migrations for a re-key) → invoke axiom-data — but take the identity rules from music-library first;
persistentID is not a durable key
MusicAuthorization prompt copy / privacy manifest → invoke axiom-integration (privacy-ux reference)
Photo library + privacy:
- Photo picker (PHPicker, PhotosPicker) → stay here (photo-library) — no permissions needed
- Full PHPhotoLibrary access → stay here (photo-library-ref) — limited access model
- Privacy manifest for photo usage → invoke axiom-integration (privacy-ux reference)
DockKit + camera / custom inference:
- DockKit stand control, framing, motor, tracking states → stay here (dockkit)
- Underlying AVCaptureSession setup → stay here (camera-capture)
- Custom Vision / Core ML inference feeding observations → invoke axiom-vision
- Camera permission (NSCameraUsageDescription) → invoke axiom-integration (privacy-ux reference)
MediaIntelligence + Vision (faces, image analysis):
- Group faces into people across a library, video highlights / key frames → stay here (media-intelligence) — clustering identities + on-device video moment detection
- Detect where a face is in one image (bounding box, landmarks), OCR, segmentation → invoke axiom-vision — per-image detection, a different problem
- System Photos "People" album → that album is system-owned (PhotoKit); MediaIntelligence builds your own index over assets you manage → stay here (photo-library for the asset access)
Anti-Rationalization
| Thought |
Reality |
| "Camera capture is just AVCaptureSession setup" |
Camera has interruption handlers, rotation, and threading requirements. |
| "Camera launch is fast enough if I startRunning() early" |
Output initialization dominates launch; iOS 26 deferred start halves time-to-preview. |
| "I'll add haptics with a simple API call" |
Haptic design has patterns for each interaction type matching HIG. |
| "ShazamKit is just SHSession + a delegate" |
iOS 17+ has SHManagedSession which eliminates all AVAudioEngine boilerplate. |
| "Now Playing info is just setting metadata" |
Remote commands, artwork handling, and state sync have 15+ gotchas. |
| "I'll use UIImagePickerController for photos" |
PHPicker/PhotosPicker are the modern API — no permissions required. |
| "MediaPlayer reports fewer playlist members than MusicKit, so sync is incomplete" |
The gap is exact and permanent — MusicKit shows the catalog, MediaPlayer shows what is local, and the difference equals the entries with no playParameters. A shipped guard built on this premise silently skipped 9 of 15 playlists forever. Read skills/music-library.md. |
| "Reading the music library is just a MusicLibraryRequest" |
Reading one MusicKit property across a large library starves the cooperative pool and then wedges every later MusicKit request, with no error thrown. Batching the request is ~100x slower, not safer. |
"Song.id is a stable key I can store" |
Its format differs per device for the same library (i.… on one, bare numeric on another). Never parse it, never use it as a cross-device key. |
| "DockKit is just pairing a stand" |
Custom control needs system tracking disabled, handles inverted dock states, and two different coordinate origins. |
| "Grouping faces is just Vision face detection" |
Vision detects faces in one image; MediaIntelligence clusters them into persistent people (entities) across a whole library, with its own working directory and state. |
| "Casting to Chromecast means bundling the Google Cast SDK" |
On iOS 27, AVSystemRouting exposes non-AirPlay routes as system routes — you adopt one Apple API (observe events, start a session, drive playbackControl) instead of a per-vendor SDK. Likely EU-gated/beta — gate and keep a fallback. |
| "I'll sync SharePlay playback by broadcasting the current time over the messenger" |
The messenger has no clock. AVDelegatingPlaybackCoordinatorPlayCommand.hostClockTime gives you an absolute CMClockGetHostTimeClock() start time; hand-rolling reinvents startup barriers, seek ordering, stalls, and interruptions badly. |
| "The playback coordinator handles interruptions for me" |
Only AVPlayerPlaybackCoordinator does. AVDelegatingPlaybackCoordinator adds no automatic suspensions — a custom engine begins and ends every one, and a suspension never ended hangs the whole group. |
| "ScreenCaptureKit on iPad works like the Mac (enumerate displays/windows)" |
On iOS/iPadOS SCShareableContent and all SCContentFilter initializers are macOS-only — you get a filter ONLY from the system SCContentSharingPicker. New on iOS/iPadOS/tvOS/visionOS 27. Also not ImageRenderer (that snapshots your own SwiftUI view). |
Example Invocations
User: "How do I set up a camera preview?"
→ Read: skills/camera-capture.md
User: "My camera app takes a second before preview appears"
→ Read: skills/camera-capture.md (Pattern 8, deferred start)
User: "Support the Center Stage front camera" / "Capture 48MP photos"
→ Read: skills/camera-capture-ref.md
User: "Camera freezes when I get a phone call"
→ Read: skills/camera-capture-diag.md
User: "How do I let users pick photos in SwiftUI?"
→ Read: skills/photo-library.md
User: "Implement haptic feedback for button taps"
→ Read: skills/haptics.md
User: "Now Playing info doesn't appear on Lock Screen"
→ Read: skills/now-playing.md
User: "How do I identify songs with ShazamKit?"
→ Read: skills/shazamkit.md
User: "How do I detect a song's tempo / key / beat grid on-device?" / "Analyze audio loudness or structure"
→ Read: skills/music-understanding.md
User: "Group faces into people across my photo library" / "cluster faces on-device" / "find highlights or a thumbnail frame in a video"
→ Read: skills/media-intelligence.md
User: "Cast to Chromecast / Google Cast without the Cast SDK" / "support non-AirPlay casting" / "route media to a DLNA device as a system route"
→ Read: skills/system-media-routing.md
User: "Record / stream the iPad screen" / "ScreenCaptureKit on iOS" / "screen recording in my app" / "capture just my app's content"
→ Read: skills/screen-capture.md
User: "List every song in the user's Apple Music library" / "enumerate their playlists" / "MPMediaQuery vs MusicKit" / "sync Apple Music playlists" / "MediaPlayer and MusicKit report different playlist counts" / "my MusicKit requests stop responding after a library scan" / "store a stable id for each song across devices" / "playlists went empty after the user turned on Sync Library"
→ Read: skills/music-library.md
User: "Track a subject with a motorized stand" / "Control a DockKit gimbal"
→ Read: skills/dockkit.md
User: "Check my camera code for issues"
→ Launch: camera-auditor agent
1---2name: axiom-media3description: Use when working with camera, photos, audio, haptics, ShazamKit, the user's Apple Music library, or Now Playing. Covers AVCaptureSession, PHPicker, PhotosPicker, AVFoundation, Core Haptics, audio recognition, MediaPlayer, CarPlay, MusicKit playback and library enumeration.4license: MIT5---6
7# Media
8
9**You MUST use this skill for ANY camera, photo, audio, haptic, or media playback work.**
10
11<!-- AXIOM_AUDITOR_INLINE_BEGIN — rewritten for Codex by scripts/build-codex.ts; do not hand-edit -->
12> **Auditors are skills here.** Where this router says "Launch `some-auditor` agent", invoke the
13> matching Codex skill instead — same procedure, no Claude Code agent required.
14>
15> Available: `axiom-audit-camera`.
16>
17> The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run.
18<!-- AXIOM_AUDITOR_INLINE_END -->
19
20## Quick Reference
21
22| Symptom / Task | Reference |
23|----------------|-----------|
24| Camera capture, AVCaptureSession | See `skills/camera-capture.md` |
25| Slow camera launch / deferred start (iOS 26+), ProRes recording via Pro Video Storage (`OS27`) | See `skills/camera-capture.md` Patterns 8-9 |
26| Camera API (RotationCoordinator, etc.) | See `skills/camera-capture-ref.md` |
27| Center Stage front camera (iPhone 17), dynamic aspect ratio, smart framing, 24/48 MP capture | See `skills/camera-capture-ref.md` |
28| Camera freezes, black preview, rotation | See `skills/camera-capture-diag.md` |
29| Photo pickers, library access | See `skills/photo-library.md` |
30| PHPicker, PhotosPicker API reference | See `skills/photo-library-ref.md` |
31| PhotoKit + Swift 6 strict concurrency, `nonisolated` observer, `performChanges` isolation, `_dispatch_assert_queue_fail` | See axiom-concurrency (skills/isolation-inheritance-diag.md) |
32| Audio, AVFoundation, spatial audio | See `skills/avfoundation-ref.md` |
33| Video write/export/playback, sample-buffer engine, resumable export, Apple Log 2, iOS 27 deprecations (`OS27`) | See `skills/avfoundation-video-ref.md` |
34| Audio recognition, ShazamKit | See `skills/shazamkit.md` |
35| ShazamKit API reference | See `skills/shazamkit-ref.md` |
36| On-device music analysis (key, tempo, structure, loudness), MusicUnderstanding (`OS27`) | See `skills/music-understanding.md` |
37| On-device face grouping (cluster faces into people across a library), video highlights/key frames, MediaIntelligence (`OS27`) | See `skills/media-intelligence.md` |
38| Haptic feedback, Core Haptics | See `skills/haptics.md` |
39| SharePlay coordinated playback, AVDelegatingPlaybackCoordinator, custom-engine sync | See `skills/shareplay-playback.md` |
40| SharePlay session lifecycle, activation, non-media state | Use axiom-integration (`skills/shareplay.md`) instead |
41| Now Playing metadata, remote commands | See `skills/now-playing.md` |
42| Animated lock-screen artwork (iOS 26+) | See `skills/now-playing.md` Pattern 8 |
43| NowPlaying framework (`import NowPlaying`, Swift-native `MediaSession`, `OS27`) | See `skills/now-playing.md` (NowPlaying Framework section) |
44| Cast / route media to non-AirPlay devices (Google Cast/Chromecast, DLNA) as system routes, AVSystemRouting (`iOS27`, EU-gated/beta) | See `skills/system-media-routing.md` |
45| Screen capture / recording / streaming the screen or your own app, ScreenCaptureKit (`OS27` — new on iOS/iPadOS/tvOS/visionOS 27; macOS 12.3+) | See `skills/screen-capture.md` |
46| CarPlay HIG, app categories, design rules, entitlements | See `skills/carplay-hig.md` |
47| CarPlay templates reference (all 12 templates, availability matrix, depth limits) | See `skills/carplay-templates-ref.md` |
48| CarPlay navigation reference (base view, route guidance, cluster/HUD, multitouch, voice prompts, map panels + EV charging iOS 27) | See `skills/carplay-navigation-ref.md` |
49| CarPlay Now Playing template customization + sports mode | See `skills/now-playing-carplay.md` |
50| MusicKit Now Playing, ApplicationMusicPlayer playback, subscription/authorization | See `skills/now-playing-musickit.md` |
51| Enumerate the user's Apple Music **library** — MusicLibraryRequest vs MPMediaQuery, reconciling the two, playlist entries, sync, library identity, per-device `Song.id`, missing `PlayParameters`, MusicKit bulk-property pool starvation | See `skills/music-library.md` |
52| DockKit motorized stands / gimbals, subject tracking, custom motor control | See `skills/dockkit.md` |
53| Speech-to-text / transcription (SpeechAnalyzer, mic → transcript) | **Invoke axiom-ai** (`skills/ios-ml.md`) |
54
55## Decision Tree
56
57```dot
58digraph media {
59 start [label="Media task" shape=ellipse];
60 what [label="Which media feature?" shape=diamond];
61
62 start -> what;
63 what -> "skills/camera-capture.md" [label="camera capture"];
64 what -> "skills/photo-library.md" [label="photo pickers\n/ library"];
65 what -> "skills/avfoundation-ref.md" [label="audio / AVFoundation"];
66 what -> "skills/avfoundation-video-ref.md" [label="video write/export\n/ sample-buffer (OS27)"];
67 what -> "skills/shazamkit.md" [label="ShazamKit\n/ audio recognition"];
68 what -> "skills/music-understanding.md" [label="music analysis\n(key/tempo/structure)"];
69 what -> "skills/media-intelligence.md" [label="face grouping /\nvideo highlights (OS27)"];
70 what -> "skills/haptics.md" [label="haptic feedback"];
71 what -> "skills/now-playing.md" [label="Now Playing\n/ remote commands"];
72 what -> "skills/music-library.md" [label="enumerate Apple Music\nlibrary / identity"];
73 what -> "skills/system-media-routing.md" [label="cast to non-AirPlay\n(Chromecast/DLNA, iOS27)"];
74 what -> "skills/screen-capture.md" [label="screen capture /\nrecording (OS27)"];
75 what -> "skills/carplay-hig.md" [label="CarPlay app design\n/ categories / entitlements"];
76 what -> "skills/dockkit.md" [label="DockKit stands\n/ gimbals / tracking"];
77}
78```
79
801. Camera capture? → `skills/camera-capture.md` (patterns), `skills/camera-capture-ref.md` (API), `skills/camera-capture-diag.md` (debugging)
812. Photo pickers / library? → `skills/photo-library.md`, `skills/photo-library-ref.md`
823. Audio / AVFoundation (audio)? → `skills/avfoundation-ref.md`; video write/export/playback, sample-buffer engine, resumable export, iOS 27 deprecations? → `skills/avfoundation-video-ref.md` (`OS27`)
834. ShazamKit / audio recognition? → `skills/shazamkit.md`, `skills/shazamkit-ref.md`
845. On-device music analysis (key, tempo, structure, pace, instruments, loudness)? → `skills/music-understanding.md` (`OS27`)
856. On-device face grouping (cluster faces into people across a library) or video highlights / key-frame detection? → `skills/media-intelligence.md` (`OS27`)
867. Haptics? → `skills/haptics.md`
878. Now Playing / remote commands? → `skills/now-playing.md`, `skills/now-playing-carplay.md`, `skills/now-playing-musickit.md`
889. Reading the user's Apple Music **library** (enumerate songs/playlists, library identity, sync)? → `skills/music-library.md` — a different problem from playback; read it before any library walk
8910. Cast / route media to non-AirPlay devices (Google Cast/Chromecast, DLNA) as system routes? → `skills/system-media-routing.md` (`iOS27`, EU-gated/beta)
9011. Screen capture / recording / streaming the screen or your own app (ScreenCaptureKit)? → `skills/screen-capture.md` (`OS27` — new on iOS/iPadOS/tvOS/visionOS 27)
9112. CarPlay app design, category selection, entitlement request? → `skills/carplay-hig.md` (start here for any CarPlay work)
9213. DockKit motorized stands / gimbals, subject tracking, custom motor control? → `skills/dockkit.md`
9314. Want camera code audit? → `axiom-audit-camera` (detects deprecated APIs and architectural gaps: missing interruption handlers, runtime-error recovery, audio session deactivation, permission-denied UX, RotationCoordinator on iOS 17+; scores RELIABLE / FRAGILE / BROKEN)
94
95## Cross-Domain Routing
96
97**Camera + permissions** (camera access denied, Info.plist missing):
98- Camera code → **stay here** (camera-capture)
99- Privacy manifest / Info.plist → **invoke axiom-integration** (privacy-ux reference)
100- Build/entitlement errors → **invoke axiom-build**
101
102**ShazamKit + microphone permissions**:
103- Microphone NSMicrophoneUsageDescription → **invoke axiom-integration** (privacy-ux reference)
104- ShazamKit API and matching → **stay here** (shazamkit)
105
106**Now Playing + background audio**:
107- Now Playing metadata/controls → **stay here** (now-playing)
108- Background audio mode / BGTaskScheduler → **invoke axiom-integration** (background-processing reference)
109
110**Speech-to-text + audio capture** (transcribing mic or asset audio):
111- `SpeechAnalyzer` / `SpeechTranscriber`, the ~2-simultaneous-analyzer cap, the `OS27` input providers → **invoke axiom-ai** (`skills/ios-ml.md`)
112- Audio session category/mode, `AVCaptureSession` wiring → **stay here** (avfoundation-ref, camera-capture)
113- **The trap**: `CaptureInputSequenceProvider.providerWithSession(...)` (`OS27`) automatically reconfigures your app's default `AVAudioSession`. If this suite's audio-session setup "randomly breaks" after transcription is added, that's the cause — use `provider(from:in:)` and add its `captureAudioDataOutput` to your own session.
114
115**Apple Music library + playback + persistence**:
116- Enumerating the library, library identity, `PlayParameters` availability, Sync Library hazards → **stay here** (music-library)
117- Queuing and playing what you found, Now Playing publishing → **stay here** (now-playing-musickit)
118- Storing library rows in your own database (which column is the durable key, migrations for a re-key) → **invoke axiom-data** — but take the identity rules from music-library first; `persistentID` is not a durable key
119- `MusicAuthorization` prompt copy / privacy manifest → **invoke axiom-integration** (privacy-ux reference)
120
121**Photo library + privacy**:
122- Photo picker (PHPicker, PhotosPicker) → **stay here** (photo-library) — no permissions needed
123- Full PHPhotoLibrary access → **stay here** (photo-library-ref) — limited access model
124- Privacy manifest for photo usage → **invoke axiom-integration** (privacy-ux reference)
125
126**DockKit + camera / custom inference**:
127- DockKit stand control, framing, motor, tracking states → **stay here** (dockkit)
128- Underlying AVCaptureSession setup → **stay here** (camera-capture)
129- Custom Vision / Core ML inference feeding observations → **invoke axiom-vision**
130- Camera permission (NSCameraUsageDescription) → **invoke axiom-integration** (privacy-ux reference)
131
132**MediaIntelligence + Vision** (faces, image analysis):
133- Group faces into people across a library, video highlights / key frames → **stay here** (media-intelligence) — clustering identities + on-device video moment detection
134- Detect *where* a face is in one image (bounding box, landmarks), OCR, segmentation → **invoke axiom-vision** — per-image detection, a different problem
135- System Photos "People" album → that album is system-owned (PhotoKit); MediaIntelligence builds *your own* index over assets you manage → **stay here** (photo-library for the asset access)
136
137## Anti-Rationalization
138
139| Thought | Reality |
140|---------|---------|
141| "Camera capture is just AVCaptureSession setup" | Camera has interruption handlers, rotation, and threading requirements. |
142| "Camera launch is fast enough if I startRunning() early" | Output initialization dominates launch; iOS 26 deferred start halves time-to-preview. |
143| "I'll add haptics with a simple API call" | Haptic design has patterns for each interaction type matching HIG. |
144| "ShazamKit is just SHSession + a delegate" | iOS 17+ has SHManagedSession which eliminates all AVAudioEngine boilerplate. |
145| "Now Playing info is just setting metadata" | Remote commands, artwork handling, and state sync have 15+ gotchas. |
146| "I'll use UIImagePickerController for photos" | PHPicker/PhotosPicker are the modern API — no permissions required. |
147| "MediaPlayer reports fewer playlist members than MusicKit, so sync is incomplete" | The gap is exact and permanent — MusicKit shows the catalog, MediaPlayer shows what is local, and the difference equals the entries with no `playParameters`. A shipped guard built on this premise silently skipped 9 of 15 playlists forever. Read `skills/music-library.md`. |
148| "Reading the music library is just a MusicLibraryRequest" | Reading one MusicKit property across a large library starves the cooperative pool and then wedges every later MusicKit request, with no error thrown. Batching the request is ~100x *slower*, not safer. |
149| "`Song.id` is a stable key I can store" | Its *format* differs per device for the same library (`i.…` on one, bare numeric on another). Never parse it, never use it as a cross-device key. |
150| "DockKit is just pairing a stand" | Custom control needs system tracking disabled, handles inverted dock states, and two different coordinate origins. |
151| "Grouping faces is just Vision face detection" | Vision detects faces in one image; MediaIntelligence clusters them into persistent people (entities) across a whole library, with its own working directory and state. |
152| "Casting to Chromecast means bundling the Google Cast SDK" | On iOS 27, AVSystemRouting exposes non-AirPlay routes as system routes — you adopt one Apple API (observe events, start a session, drive playbackControl) instead of a per-vendor SDK. Likely EU-gated/beta — gate and keep a fallback. |
153| "I'll sync SharePlay playback by broadcasting the current time over the messenger" | The messenger has no clock. `AVDelegatingPlaybackCoordinatorPlayCommand.hostClockTime` gives you an absolute `CMClockGetHostTimeClock()` start time; hand-rolling reinvents startup barriers, seek ordering, stalls, and interruptions badly. |
154| "The playback coordinator handles interruptions for me" | Only `AVPlayerPlaybackCoordinator` does. `AVDelegatingPlaybackCoordinator` adds **no** automatic suspensions — a custom engine begins *and* ends every one, and a suspension never ended hangs the whole group. |
155| "ScreenCaptureKit on iPad works like the Mac (enumerate displays/windows)" | On iOS/iPadOS `SCShareableContent` and all `SCContentFilter` initializers are macOS-only — you get a filter ONLY from the system `SCContentSharingPicker`. New on iOS/iPadOS/tvOS/visionOS 27. Also not `ImageRenderer` (that snapshots your own SwiftUI view). |
156
157## Example Invocations
158
159User: "How do I set up a camera preview?"
160→ Read: `skills/camera-capture.md`
161
162User: "My camera app takes a second before preview appears"
163→ Read: `skills/camera-capture.md` (Pattern 8, deferred start)
164
165User: "Support the Center Stage front camera" / "Capture 48MP photos"
166→ Read: `skills/camera-capture-ref.md`
167
168User: "Camera freezes when I get a phone call"
169→ Read: `skills/camera-capture-diag.md`
170
171User: "How do I let users pick photos in SwiftUI?"
172→ Read: `skills/photo-library.md`
173
174User: "Implement haptic feedback for button taps"
175→ Read: `skills/haptics.md`
176
177User: "Now Playing info doesn't appear on Lock Screen"
178→ Read: `skills/now-playing.md`
179
180User: "How do I identify songs with ShazamKit?"
181→ Read: `skills/shazamkit.md`
182
183User: "How do I detect a song's tempo / key / beat grid on-device?" / "Analyze audio loudness or structure"
184→ Read: `skills/music-understanding.md`
185
186User: "Group faces into people across my photo library" / "cluster faces on-device" / "find highlights or a thumbnail frame in a video"
187→ Read: `skills/media-intelligence.md`
188
189User: "Cast to Chromecast / Google Cast without the Cast SDK" / "support non-AirPlay casting" / "route media to a DLNA device as a system route"
190→ Read: `skills/system-media-routing.md`
191
192User: "Record / stream the iPad screen" / "ScreenCaptureKit on iOS" / "screen recording in my app" / "capture just my app's content"
193→ Read: `skills/screen-capture.md`
194
195User: "List every song in the user's Apple Music library" / "enumerate their playlists" / "MPMediaQuery vs MusicKit" / "sync Apple Music playlists" / "MediaPlayer and MusicKit report different playlist counts" / "my MusicKit requests stop responding after a library scan" / "store a stable id for each song across devices" / "playlists went empty after the user turned on Sync Library"
196→ Read: `skills/music-library.md`
197
198User: "Track a subject with a motorized stand" / "Control a DockKit gimbal"
199→ Read: `skills/dockkit.md`
200
201User: "Check my camera code for issues"
202→ Launch: `camera-auditor` agent
charleswiltgen