Shiny.Music 1.3.1

Shiny.Music

A .NET library for accessing the device music library on Android and iOS. Provides a unified API for:

• 🔐 Requesting permissions to access music
• 🎵 Querying metadata about music on the device
• 🔎 Filtering tracks by genre, year, decade, and search text
• 📊 Browsing genres, years, and decades with track counts
• 📋 Browsing playlists and their tracks
• ▶️ Playing music files from the device library
• 🎧 Streaming Apple Music subscription tracks via MPMusicPlayerController (iOS)
• 📁 Copying music files (where permitted)
• 🔍 Checking for active streaming subscriptions

Installation

Add a project reference to Shiny.Music from your .NET MAUI or platform-specific app.

Quick Start

// Register in MauiProgram.cs
builder.Services.AddShinyMusic();

// Use via dependency injection
public class MyPage
{
    readonly IMediaLibrary _library;
    readonly IMusicPlayer _player;

    public MyPage(IMediaLibrary library, IMusicPlayer player)
    {
        _library = library;
        _player = player;
    }

    async Task Example()
    {
        // 1. Request permission
        var status = await _library.RequestPermissionAsync();
        if (status != PermissionStatus.Granted) return;

        // 2. Get all tracks
        var tracks = await _library.GetAllTracksAsync();

        // 3. Play a track
        await _player.PlayAsync(tracks[0]);

        // 4. Browse genres with counts
        var genres = await _library.GetGenresAsync();

        // 5. Browse decades with counts
        var decades = await _library.GetDecadesAsync();

        // 6. Filter: Rock tracks from the 1990s
        var filtered = await _library.GetTracksAsync(new MusicFilter
        {
            Genre = "Rock",
            Decade = 1990
        });

        // 7. Cross-query: genres within the 2000s
        var genresIn2000s = await _library.GetGenresAsync(new MusicFilter { Decade = 2000 });

        // 8. Browse playlists
        var playlists = await _library.GetPlaylistsAsync();

        // 9. Get tracks in a playlist
        var playlistTracks = await _library.GetPlaylistTracksAsync(playlists[0].Id);

        // 10. Copy a track
        var dest = Path.Combine(FileSystem.AppDataDirectory, "copy.m4a");
        var success = await _library.CopyTrackAsync(tracks[0], dest);
    }
}

Platform Configuration

Android

Required Permissions

Add these to your AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />


<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
                 android:maxSdkVersion="32" />

Notes

• Minimum API Level: 24 (Android 7.0)
• Target API 33+: Uses READ_MEDIA_AUDIO granular media permission
• Target API < 33: Falls back to READ_EXTERNAL_STORAGE
• The library requests runtime permissions via the MAUI Permissions API
• Music is queried through MediaStore.Audio.Media; playlists through MediaStore.Audio.Playlists
• Playback uses Android.Media.MediaPlayer with content URIs
• HasStreamingSubscriptionAsync() always returns false
• Copy: Reads from the ContentResolver input stream. Works for all locally stored music files.

iOS

Required Info.plist Entry

<key>NSAppleMusicUsageDescription</key>
<string>This app needs access to your music library to browse and play your music.</string>

⚠️ This is mandatory. Your app will crash on launch if you attempt to access the music library without this key.

Notes

• Minimum iOS Version: 15.0
• Permission is requested via MPMediaLibrary.RequestAuthorization
• Music metadata is queried using MPMediaQuery from the MediaPlayer framework; playlists via MPMediaQuery.PlaylistsQuery
• Local playback uses AVAudioPlayer from AVFoundation with the item's AssetURL
• Streaming playback uses MPMusicPlayerController.SystemMusicPlayer for Apple Music subscription tracks with a StoreId
• HasStreamingSubscriptionAsync() checks SKCloudServiceController for the MusicCatalogPlayback capability
• Copy Limitations:
  • ✅ Locally synced / purchased (non-DRM) tracks can be exported via AVAssetExportSession
  • ❌ Apple Music subscription (DRM-protected) tracks cannot be copied. The AssetURL is empty for these items, and iOS does not provide filesystem access to DRM content.
  • The CopyTrackAsync method returns false for tracks that cannot be exported.
  • Exported format is Apple M4A (.m4a)

Entitlements

No special entitlements are required beyond the Info.plist usage description. The MediaPlayer and AVFoundation frameworks are standard iOS frameworks.

API Reference

IMediaLibrary

MusicFilter

All properties are optional and combined with AND logic. Pass to GetTracksAsync, GetGenresAsync, GetYearsAsync, or GetDecadesAsync.

GroupedCount<T>

Returned by GetGenresAsync, GetYearsAsync, and GetDecadesAsync.

PlaylistInfo

IMusicPlayer

MusicMetadata

Sample App

The sample/MusicSample project is a .NET MAUI app that demonstrates all library features:

1. Permission Request — Tap "Request Permission" to prompt for music access
2. Browse — Tap "Load All" to list all music on the device
3. Search — Type a query and tap "Search" to filter by title/artist/album
4. Play/Pause/Stop — Select a track and use the playback controls
5. Copy — Select a track and tap "Copy" to export it to app storage
6. Genres — Switch to the "Genres" tab to view all distinct genres with track counts
7. Decades — Switch to the "Decades" tab to view decades with track counts
8. Years — Switch to the "Years" tab to view release years with track counts
9. Playlists — Switch to the "Playlists" tab to view playlists and their tracks

Running the Sample

# Android
dotnet build sample/MusicSample -f net9.0-android -t:Run

# iOS (requires Mac with Xcode)
dotnet build sample/MusicSample -f net9.0-ios -t:Run

Note: Music library access requires a physical device. Simulators/emulators typically have no music content.

License

MIT