Shiny.Music.Sqlite 2.1.0-beta-0011

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
• Controlling playback volume
• Streaming Apple Music subscription tracks via MPMusicPlayerController (iOS)
• Identifying songs by listening to audio (iOS via ShazamKit)
• Fetching lyrics (plain text and synced LRC format)
• Retrieving album artwork
• Copying music files (where permitted)
• Checking for active streaming subscriptions
• Managing custom playlists and play counts via IMusicManager (backed by SQLite)

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();
builder.Services.AddMusicManagementSqlite(); // Optional: custom playlists & play counts

// Use via dependency injection
public class MyPage
{
    readonly IMediaLibrary _library;
    readonly IMusicPlayer _player;
    readonly ILyricsProvider _lyrics;
    readonly IMusicManager _manager;

    public MyPage(IMediaLibrary library, IMusicPlayer player, ILyricsProvider lyrics, IMusicManager manager)
    {
        _library = library;
        _player = player;
        _lyrics = lyrics;
        _manager = manager;
    }

    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. Control volume
        _player.Volume = 0.75f;

        // 5. Get album artwork
        var artPath = await _library.GetAlbumArtPathAsync(tracks[0].Id);

        // 6. Fetch lyrics
        var lyrics = await _lyrics.GetLyricsAsync(tracks[0]);

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

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

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

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

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

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

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

        // 14. Identify a song (iOS only)
        var identifier = /* resolve IMusicIdentifier from DI */;
        var identified = await identifier.ListenAsync();
        if (identified != null)
            Console.WriteLine($"Identified: {identified.Title} by {identified.Artist}");

        // 15. Track play counts
        await _manager.AddPlayCount(tracks[0].Id);
        var count = await _manager.GetPlayCount(tracks[0].Id);

        // 16. Custom playlists
        await _manager.CreatePlaylist("my-id", "Favorites");
        await _manager.AddTrackToPlaylist("my-id", tracks[0]);
        var customTracks = await _manager.GetPlaylistTracks("my-id");

        // 17. Browse all custom playlists
        var customPlaylists = await _manager.GetAllPlaylists();
    }
}

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.

For song identification via IMusicIdentifier, also add:

<key>NSMicrophoneUsageDescription</key>
<string>Used to identify songs playing nearby.</string>

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

IMusicPlayer

IMusicIdentifier

MusicIdentificationResult

ILyricsProvider

LyricsResult

MusicFilter

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

MusicMetadata

PlaylistInfo

IMusicManager

Custom playlist management and play count tracking, backed by SQLite via Shiny.DocumentDb. Registered with AddMusicManagementSqlite().

PlayCount

GroupedCount<T>

Sample App

The sample/MusicSample project is a .NET MAUI app that demonstrates all library features including browsing, filtering, playback with volume control, album art display, and lyrics with synced highlighting.

Running the Sample

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

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

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

License

MIT