Updates

Author: aritchie

src/content/docs/client/music/index.mdx

@@ -12,6 +12,8 @@ Shiny.Music provides a unified API for accessing the device music library on **A
 * Request and check music library permissions on both platforms
 * Query all music tracks or search by title, artist, or album
 * Play, pause, resume, stop, and seek within tracks
+* Stream Apple Music subscription tracks via `MPMusicPlayerController` on iOS
+* Check for active streaming subscriptions
 * Copy music files to app storage (non-DRM content only on iOS)
 * Event-driven playback state changes and completion notifications
 
@@ -22,8 +24,10 @@ Shiny.Music provides a unified API for accessing the device music library on **A
 | Permission Request | ✅ | ✅ |
 | Query Tracks | ✅ | ✅ |
 | Search Tracks | ✅ | ✅ |
-| Playback | ✅ | ✅ |
+| Local Playback | ✅ | ✅ (AVPlayer) |
+| Streaming Playback | ❌ | ✅ (MPMusicPlayerController via StoreId) |
 | Copy Track | ✅ | ✅ (non-DRM only) |
+| Streaming Subscription Check | ❌ (always `false`) | ✅ (SKCloudServiceController) |
 | Album Art URI | ✅ | ❌ (use MPMediaItem.Artwork) |
 | Explicit Flag | ❌ | ✅ (via MPMediaItem.IsExplicitItem) |
 

src/content/docs/client/music/playback.md

@@ -4,17 +4,21 @@ title: Playback
 
 The `IMusicPlayer` interface provides full playback control for music tracks from the device library.
 
+On iOS, the player supports two modes that are automatically selected based on the track's properties:
+- **Local playback** via `AVPlayer` when `ContentUri` is available (purchased/synced tracks)
+- **Streaming playback** via `MPMusicPlayerController.SystemMusicPlayer` when `StoreId` is available (Apple Music subscription tracks)
+
 ## Playing a Track
 
 ```csharp
 var tracks = await _library.GetAllTracksAsync();
 await _player.PlayAsync(tracks[0]);
 ```
 
-Calling `PlayAsync` stops any currently playing track, loads the new one, and begins playback immediately.
+Calling `PlayAsync` stops any currently playing track, loads the new one, and begins playback immediately. The player automatically selects the appropriate playback engine based on whether `StoreId` or `ContentUri` is available.
 
 :::caution
-`PlayAsync` will throw an `InvalidOperationException` if the track's `ContentUri` is empty (DRM-protected on iOS) or if the platform player fails to initialize. Always check `ContentUri` before playing.
+`PlayAsync` will throw an `InvalidOperationException` if both `ContentUri` and `StoreId` are empty, or if the platform player fails to initialize.
 :::
 
 ## Pause, Resume, and Stop
@@ -98,9 +102,8 @@ If you register the player as a singleton in DI, it will be disposed when the ap
 - Seeking uses millisecond precision.
 
 ### iOS
-- Playback uses `AVFoundation.AVAudioPlayer` with the track's `ipod-library://` asset URL.
-- The `AVAudioSession` category is set to `Playback` to support background audio (if configured).
-- Seeking uses second precision.
+- **Local tracks** (with `ContentUri`): Playback uses `AVPlayer` with the track's `ipod-library://` asset URL. The `AVAudioSession` category is set to `Playback` to support background audio (if configured). Seeking uses second precision.
+- **Streaming tracks** (with `StoreId`): Playback uses `MPMusicPlayerController.SystemMusicPlayer` with the Apple Music catalog ID. This enables playback of DRM-protected Apple Music subscription content. The system player manages its own audio session.
 
 :::note
 Music library access requires a **physical device**. Simulators and emulators typically have no music content and cannot test playback.

src/content/docs/client/music/querying.md

@@ -39,40 +39,45 @@ Each track is represented by a `MusicMetadata` record with the following propert
 | Property | Type | Description |
 |---|---|---|
 | `Id` | `string` | Platform-specific unique identifier. On Android, this is the MediaStore row ID. On iOS, it is the `MPMediaItem` persistent ID. |
-| `Title` | `string` | The track title. |
-| `Artist` | `string` | The artist or performer. |
-| `Album` | `string` | The album name. |
+| `Title` | `string?` | The track title, or `null` if not available. |
+| `Artist` | `string?` | The artist or performer, or `null` if not available. |
+| `Album` | `string?` | The album name, or `null` if not available. |
 | `Genre` | `string?` | The genre, or `null` if unavailable. |
 | `Duration` | `TimeSpan` | The playback duration. |
 | `AlbumArtUri` | `string?` | URI to album artwork. Available on Android via MediaStore; `null` on iOS where artwork is accessed through `MPMediaItem.Artwork`. |
 | `IsExplicit` | `bool?` | Whether the track is marked as explicit content. iOS only via `MPMediaItem.IsExplicitItem`; always `null` on Android. |
 | `ContentUri` | `string` | URI used for playback and file operations. On Android, this is a `content://` URI. On iOS, this is an `ipod-library://` asset URL. **Empty for DRM-protected Apple Music subscription tracks.** |
+| `StoreId` | `string?` | Apple Music catalog ID (from `PlayParams.Id`). Enables streaming playback via `MPMusicPlayerController` on iOS. Always `null` on Android. |
 
-## ContentUri and DRM
+## ContentUri, StoreId, and DRM
 
-The `ContentUri` property is critical for understanding what operations are available for a track:
+The `ContentUri` and `StoreId` properties determine what operations are available for a track:
 
 ```csharp
 var tracks = await _library.GetAllTracksAsync();
 
 foreach (var track in tracks)
 {
-    if (string.IsNullOrEmpty(track.ContentUri))
+    if (!string.IsNullOrEmpty(track.ContentUri))
     {
-        // DRM-protected Apple Music track
-        // Cannot be played via AVAudioPlayer or copied
-        Console.WriteLine($"⚠️ {track.Title} - DRM protected, playback/copy unavailable");
+        // Locally synced or purchased track — full access
+        Console.WriteLine($"✅ {track.Title} - available for local playback and copy");
+    }
+    else if (!string.IsNullOrEmpty(track.StoreId))
+    {
+        // Apple Music subscription track with catalog ID — streaming playback only
+        Console.WriteLine($"🎧 {track.Title} - available for streaming playback (no copy)");
     }
     else
     {
-        // Locally synced or purchased track — full access
-        Console.WriteLine($"✅ {track.Title} - available for playback and copy");
+        // No playback or copy available
+        Console.WriteLine($"⚠️ {track.Title} - not playable or copyable");
     }
 }
 ```
 
 :::note
-On Android, `ContentUri` is always populated for all music files. The DRM limitation only applies to iOS Apple Music subscription tracks.
+On Android, `ContentUri` is always populated for all music files. `StoreId` is always `null` on Android. The DRM and streaming distinction only applies to iOS Apple Music subscription tracks.
 :::
 
 ## Platform Details

src/content/docs/client/music/release-notes.mdx

@@ -13,7 +13,10 @@ import RN from '/src/components/ReleaseNote.astro';
 <RN type="feature">Audio playback — play, pause, resume, and stop music files with state change and completion events</RN>
 <RN type="feature">File copying — copy music files to app-local storage (where DRM permits)</RN>
 <RN type="feature">Dependency injection — `AddShinyMusic()` extension method for `IServiceCollection` registration</RN>
+<RN type="feature">`HasStreamingSubscriptionAsync()` — check for active Apple Music subscription capability on iOS</RN>
+<RN type="feature">`StoreId` property on `MusicMetadata` — Apple Music catalog ID enabling streaming playback of subscription content</RN>
 <RN type="feature" platform="Android">Android implementation using `MediaStore.Audio.Media` and `Android.Media.MediaPlayer`</RN>
-<RN type="feature" platform="iOS">iOS implementation using `MPMediaQuery` and `AVFoundation.AVAudioPlayer`</RN>
-<RN type="feature" platform="iOS">DRM-aware — `ContentUri` is empty for Apple Music subscription tracks that cannot be played or copied</RN>
+<RN type="feature" platform="iOS">iOS implementation using `MPMediaQuery` and `AVPlayer`</RN>
+<RN type="feature" platform="iOS">Streaming playback of Apple Music subscription tracks via `MPMusicPlayerController.SystemMusicPlayer` using `StoreId`</RN>
+<RN type="feature" platform="iOS">DRM-aware — `ContentUri` is empty for Apple Music subscription tracks that cannot be copied, but streaming playback is available via `StoreId`</RN>
 <RN type="feature" platform="iOS">`IsExplicit` property on `MusicMetadata` — reports whether a track is marked as explicit content via `MPMediaItem.IsExplicitItem`</RN>