Shiny.Music.Extensions.AI 4.0.0-beta

Shiny.Music

A .NET library for accessing the device music library on Android, iOS, and Mac Catalyst. 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
• Fetching lyrics (plain text and synced LRC format)
• Retrieving album artwork
• Copying music files (where permitted)
• Checking for active streaming subscriptions
• Managing playlists — create, remove, and add/remove tracks via IMediaLibrary
• Automatic play count tracking (Apple platforms via MPMediaItem, Android via local storage)

Installation

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

Quick Start

// Register in MauiProgram.cs
builder
    .UseMauiApp<App>()
    .UseShiny();          // required — Android permission checks run on Shiny.Core (see below)

builder.Services.AddShinyMusic();

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

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

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

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

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

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

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

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

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

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

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

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

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

        // 11b. Look up a single track / playlist by id (e.g. restoring saved state)
        var one = await _library.GetTrackByIdAsync(tracks[0].Id);
        var many = await _library.GetTracksByIdsAsync(new[] { tracks[0].Id, tracks[1].Id });
        var playlist = await _library.GetPlaylistByIdAsync(playlists[0].Id);

        // 12. Create a playlist and add tracks
        var newPlaylist = await _library.CreatePlaylistAsync("Favorites");
        await _library.AddTrackToPlaylistAsync(newPlaylist.Id, tracks[0]);

        // 13. 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
• Requires Shiny hosting (v4+): runtime permission checks use Shiny.Core's AndroidPlatform (GetCurrentPermissionStatus / RequestAccess). Call .UseShiny() in MauiProgram — or, for native Android, use ShinyAndroidApplication + ShinyAndroidActivity — so Shiny tracks the current activity and routes the permission result. Without Shiny hosting, IMediaLibrary cannot resolve AndroidPlatform.
• 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.

Apple Platforms (iOS, Mac Catalyst)

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

• Supported platforms: iOS 17.0+, Mac Catalyst 17.0+
• Permission is requested via MPMediaLibrary.RequestAuthorization
• Music metadata is queried using MPMediaQuery (MediaPlayer framework)
• Playback uses MPMusicPlayerController.ApplicationMusicPlayer for all tracks — local items by persistent ID, and streaming catalog items by catalog id via MPMusicPlayerStoreQueueDescriptor
• HasStreamingSubscriptionAsync() checks MusicKit MusicSubscription.GetCurrentAsync
• Catalog search (SearchCatalogAsync) uses MusicKit MusicCatalogSearchRequest to search the Apple Music streaming catalog — results need not be in the user's library and are playable via PlayAsync when the user has an active subscription. The first call prompts for MusicKit authorization. Catalog tracks are streaming-only (empty ContentUri, not copyable).
• Playlist management uses locally-stored custom playlists (system playlists from MPMediaQuery.PlaylistsQuery are read-only)
• Copy Limitations:
  • Non-DRM tracks can be exported via AVAssetExportSession
  • DRM-protected tracks cannot be copied. CopyTrackAsync returns false for these.
  • Exported format is Apple M4A (.m4a)

AI Tools

Shiny.Music.Extensions.AI exposes the music library and player as Microsoft.Extensions.AI tool functions for LLM agents — so a chat agent can search and browse your library, pick a track for a mood, control playback, and manage playlists. Opt-in exactly which areas the model can see. Resolve MusicAITools from DI and pass .Tools to any IChatClient. AOT-compatible.

dotnet add package Shiny.Music.Extensions.AI

using Shiny.Music.Extensions.AI;

builder.Services.AddShinyMusic();
builder.Services.AddMusicAITools(tools => tools
    .AddLibrary()             // search / browse / genres / playlists / lyrics (read-only)
    .AddPlayback()            // play, pause, resume, stop, seek, now-playing
    .AddPlaylistManagement()  // create / modify / delete custom playlists
);
// ...or simply .AddAll()  (the three cross-platform areas above)

// Apple Music catalog search is opt-in and Apple-only — guard it with a compiler flag:
// builder.Services.AddMusicAITools(tools =>
// {
//     tools.AddLibrary().AddPlayback().AddPlaylistManagement();
// #if IOS || MACCATALYST
//     tools.AddCatalog();   // exposes search_catalog (streaming catalog, not just the local library)
// #endif
// });

// later, hand the tools to a chat client
var tools = sp.GetRequiredService<MusicAITools>().Tools;
var response = await chatClient.GetResponseAsync(
    messages,
    new ChatOptions { Tools = [.. tools] }
);

Generated tools (only for areas you opt-in to):

browse_tracks filters by genre, year, decade, and free text — it's the natural path for "play me something mellow" or "pick an 80s track". The tools assume library permission is already granted — call RequestPermissionAsync from your app first; they do not trigger the permission UI.

API Reference

IMediaLibrary

IMusicPlayer

ILyricsProvider

LyricsResult

MusicFilter

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

MusicMetadata

PlaylistInfo

GroupedCount<T>

Sample App

The sample/MusicSample project is a .NET MAUI app that demonstrates all library features including browsing, filtering, playback, 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