Media
Networking Clarification
Media playback URLs are permitted. The forbidden-patterns networking ban targets REST API clients (URLSession data tasks, custom HTTP clients), not media playback. The following are allowed:
AVPlayer with remote URLs (MP4, HLS .m3u8 streams)AsyncImage loading remote image URLsKFImage (Kingfisher) loading and caching remote imagesURLSession.shared.download(from:) only for downloading media files to local storage
Do not use URLSession for REST API calls, JSON fetching, or custom networking — that ban still applies.
Decision Tree
Pick the right pattern based on what you're building:
| Building |
Reference |
Key API |
| Video player |
video-playback |
VideoPlayer, AVPlayer |
| HLS/live streaming |
video-playback |
AVPlayer + .m3u8 URL |
| Video feed (TikTok-style) |
video-playback + media-memory-management |
FeedPlayerCoordinator |
| Music/audio player |
audio-playback + audio-session |
AVAudioPlayer (local) or AVPlayer (streaming) |
| Podcast player |
audio-playback + audio-session |
AVPlayer + Now Playing + Remote Commands |
| Background audio |
audio-session |
.playback category + UIBackgroundModes |
| Image gallery/feed |
remote-images |
KFImage (Kingfisher) |
| Simple remote image |
remote-images |
AsyncImage |
| Sound effects |
audio-playback |
AVAudioPlayer with .ambient category |
| Sample content |
sample-media-urls |
Public URLs, local audio generation |
Platform Capabilities
| Feature |
iOS |
macOS |
tvOS |
watchOS |
visionOS |
| Video playback |
VideoPlayer |
AVPlayerView (NSViewRepresentable) |
VideoPlayer |
No |
VideoPlayer |
| Audio playback |
AVAudioPlayer / AVPlayer |
AVAudioPlayer / AVPlayer |
AVAudioPlayer / AVPlayer |
WKAudioFilePlayer |
AVAudioPlayer / AVPlayer |
| AVAudioSession |
Yes |
No (not needed) |
Yes |
Limited |
Yes |
| Background audio |
Yes (UIBackgroundModes) |
N/A |
No |
Limited |
Yes |
| Now Playing info |
Yes |
Yes |
Limited |
No |
Yes |
| Remote commands |
Yes |
Yes |
Limited |
No |
Yes |
| AsyncImage |
Yes |
Yes |
Yes |
Yes |
Yes |
| Kingfisher |
Yes |
Yes |
Yes |
No |
Yes |
Recommended Packages
All already in the curated package registry — no new dependencies to add:
- Kingfisher — remote image loading with disk/memory caching, prefetch, placeholder, fade. Use for image feeds and galleries (20+ images).
- DSWaveformImage — audio waveform visualization. Use for voice memo or audio editing UIs.
- AudioKit — advanced audio synthesis and processing. Only use when the user specifically needs audio effects, synthesis, or real-time audio processing.
Required Info.plist Keys
For background audio playback, add to the target's info section in project.yml:
UIBackgroundModes: ["audio"]
No other Info.plist keys are needed for basic media playback.
Cross-References
- PhotosPicker — see the
camera skill (not duplicated here)
- Camera access — see the
camera skill
- MapKit / CoreLocation — see the
maps skill (not duplicated here)
- Image containment / clip patterns — see the
swiftui skill
- Haptic feedback on media controls — see the
haptics skill
References
This skill includes the following reference documents (auto-loaded):
- video-playback — VideoPlayer, HLS streaming, custom controls, feed-style video, looping
- audio-playback — AVAudioPlayer (local), AVPlayer (streaming), Now Playing, remote commands, playlists
- audio-session — AVAudioSession categories, interruption handling, route changes, background audio
- remote-images — AsyncImage vs Kingfisher decision, image grids, feeds, prefetch, cache config
- sample-media-urls — Public video/HLS/image URLs and local audio generation with
say
- media-memory-management — Player lifecycle, observer cleanup, KVO, feed coordinator, debug checklist
1---2name: media3description: Comprehensive media patterns: video playback, audio/music players, HLS streaming, remote images, AVAudioSession, memory management. Use when implementing any media-related features.4---5# Media67## Networking Clarification89Media playback URLs are **permitted**. The forbidden-patterns networking ban targets REST API clients (URLSession data tasks, custom HTTP clients), **not** media playback. The following are allowed:1011- `AVPlayer` with remote URLs (MP4, HLS `.m3u8` streams)12- `AsyncImage` loading remote image URLs13- `KFImage` (Kingfisher) loading and caching remote images14- `URLSession.shared.download(from:)` **only** for downloading media files to local storage1516Do **not** use URLSession for REST API calls, JSON fetching, or custom networking — that ban still applies.1718## Decision Tree1920Pick the right pattern based on what you're building:2122| Building | Reference | Key API |23|----------|-----------|---------|24| Video player | video-playback | `VideoPlayer`, `AVPlayer` |25| HLS/live streaming | video-playback | `AVPlayer` + `.m3u8` URL |26| Video feed (TikTok-style) | video-playback + media-memory-management | `FeedPlayerCoordinator` |27| Music/audio player | audio-playback + audio-session | `AVAudioPlayer` (local) or `AVPlayer` (streaming) |28| Podcast player | audio-playback + audio-session | `AVPlayer` + Now Playing + Remote Commands |29| Background audio | audio-session | `.playback` category + `UIBackgroundModes` |30| Image gallery/feed | remote-images | `KFImage` (Kingfisher) |31| Simple remote image | remote-images | `AsyncImage` |32| Sound effects | audio-playback | `AVAudioPlayer` with `.ambient` category |33| Sample content | sample-media-urls | Public URLs, local audio generation |3435## Platform Capabilities3637| Feature | iOS | macOS | tvOS | watchOS | visionOS |38|---------|-----|-------|------|---------|----------|39| Video playback | VideoPlayer | AVPlayerView (NSViewRepresentable) | VideoPlayer | No | VideoPlayer |40| Audio playback | AVAudioPlayer / AVPlayer | AVAudioPlayer / AVPlayer | AVAudioPlayer / AVPlayer | WKAudioFilePlayer | AVAudioPlayer / AVPlayer |41| AVAudioSession | Yes | No (not needed) | Yes | Limited | Yes |42| Background audio | Yes (UIBackgroundModes) | N/A | No | Limited | Yes |43| Now Playing info | Yes | Yes | Limited | No | Yes |44| Remote commands | Yes | Yes | Limited | No | Yes |45| AsyncImage | Yes | Yes | Yes | Yes | Yes |46| Kingfisher | Yes | Yes | Yes | No | Yes |4748## Recommended Packages4950All already in the curated package registry — no new dependencies to add:5152- **Kingfisher** — remote image loading with disk/memory caching, prefetch, placeholder, fade. Use for image feeds and galleries (20+ images).53- **DSWaveformImage** — audio waveform visualization. Use for voice memo or audio editing UIs.54- **AudioKit** — advanced audio synthesis and processing. Only use when the user specifically needs audio effects, synthesis, or real-time audio processing.5556## Required Info.plist Keys5758For background audio playback, add to the target's `info` section in `project.yml`:5960```yaml61UIBackgroundModes: ["audio"]62```6364No other Info.plist keys are needed for basic media playback.6566## Cross-References6768- **PhotosPicker** — see the `camera` skill (not duplicated here)69- **Camera access** — see the `camera` skill70- **MapKit / CoreLocation** — see the `maps` skill (not duplicated here)71- **Image containment / clip patterns** — see the `swiftui` skill72- **Haptic feedback on media controls** — see the `haptics` skill7374## References7576This skill includes the following reference documents (auto-loaded):7778- **video-playback** — VideoPlayer, HLS streaming, custom controls, feed-style video, looping79- **audio-playback** — AVAudioPlayer (local), AVPlayer (streaming), Now Playing, remote commands, playlists80- **audio-session** — AVAudioSession categories, interruption handling, route changes, background audio81- **remote-images** — AsyncImage vs Kingfisher decision, image grids, feeds, prefetch, cache config82- **sample-media-urls** — Public video/HLS/image URLs and local audio generation with `say`83- **media-memory-management** — Player lifecycle, observer cleanup, KVO, feed coordinator, debug checklist
abdullah4ai