Add Musical Work linking and rendition management

[Copilot]

Enables linking songs as renditions of a canonical Musical Work (e.g., studio, live, piano, cello versions of the same composition). Provides intelligent matching suggestions and metadata-driven filtering without breaking existing functionality.

Implementation

Core Models

• MusicalWorkModel: Realm entity for canonical works with aggregated statistics (play counts, popularity, rendition count)
• SongModel extensions: Optional MusicalWork relationship + rendition metadata (RenditionType, Instrumentation, IsLivePerformance, IsRemix, IsCover)

Service Layer

• IMusicalWorkService: CRUD operations, link/unlink, filtered queries, statistics aggregation
• Suggestion engine: Multi-factor similarity scoring (40% title + 30% artist + 20% composer + 10% genre) using Levenshtein distance and normalized titles
• Pre-compiled regex patterns for performance

Architecture

• One-to-many via Realm backlinks (Work → Renditions)
• Manual linking only—suggestions never auto-commit
• All new fields nullable for backward compatibility

Usage

// Create work and link renditions
var work = workService.CreateWork("Bohemian Rhapsody", "Freddie Mercury", "Queen");
workService.LinkSongToWork(studioVersionId, work.Id);
workService.LinkSongToWork(liveVersionId, work.Id);

// Update metadata
workService.UpdateRenditionMetadata(liveVersionId, 
    renditionType: "Live", isLive: true);

// Filter renditions
var instrumentals = workService.GetFilteredRenditions(work.Id, 
    instrumentalOnly: true);

// Get smart suggestions
var suggestions = workService.SuggestMatchingWorks(songId, maxResults: 5);
// Returns: [{Work, ConfidenceScore, Reason}]

Testing

23 unit tests covering CRUD, linking, filtering, suggestions, statistics aggregation, and edge cases.

Notes

• Zero breaking changes—all fields optional
• Indexed for query performance (Title, TotalPlayCount, LastPlayed, RenditionCount)
• Scalability notes included for datasets >10K items
• Complete documentation in MUSICAL_WORK_FEATURE.md

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• crl.godaddy.com
  • Triggering command: /usr/bin/dotnet dotnet restore --no-dependencies /home/REDACTED/work/Dimmer-MAUI/.codeql-scratch/dbs/csharp/working/EB23B7D1B15B85081672081E55C17E18/missingpackages_workingdir --packages /home/REDACTED/work/Dimmer-MAUI/.codeql-scratch/dbs/csharp/working/missingpackages /p:DisableImplicitNuGetFallbackFolder=true --verbosity normal --configfile /home/REDACTED/work/Dimmer-MAUI/.codeql-scratch/dbs/csharp/working/nugetconfig/nuget.config --force (dns block)
• ocsp.godaddy.com
  • Triggering command: /usr/bin/dotnet dotnet restore --no-dependencies /home/REDACTED/work/Dimmer-MAUI/.codeql-scratch/dbs/csharp/working/EB23B7D1B15B85081672081E55C17E18/missingpackages_workingdir --packages /home/REDACTED/work/Dimmer-MAUI/.codeql-scratch/dbs/csharp/working/missingpackages /p:DisableImplicitNuGetFallbackFolder=true --verbosity normal --configfile /home/REDACTED/work/Dimmer-MAUI/.codeql-scratch/dbs/csharp/working/nugetconfig/nuget.config --force (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Musical Work Linking and Rendition Management</issue_title>
<issue_description>Summary:
Enable linking of related songs (e.g., instrumental, vocal, piano, cello versions) under a canonical “Musical Work” entity. This will allow better organization, querying, and UI presentation of renditions without convoluted data structures.

---

Motivation / Why

Currently, each SongModel is independent. This makes it hard to:

1. Identify songs that are renditions or variations of the same underlying composition.

2. Provide UI features like “Other Versions”, “Instrumental Only”, or “Vocals Only”.

3. Avoid duplication or cycles in the database when storing relations between songs.

This feature improves data integrity, query efficiency, and user experience, especially in libraries with multiple versions of the same work.

---

Proposed Solution

Introduce a new Musical Work abstraction:

Musical Work: The canonical idea of the song or composition.

Rendition / Track (SongModel): Concrete recording of the work, with metadata like instrumental/vocal, instrumentation, live/remix, etc.

Core Principles

1. Separation of identity from representation

The work is the “idea”; renditions are actual files or recordings.

2. One-directional relationship

SongModel links to MusicalWork as parent.

MusicalWork contains a list of renditions.

Avoid cycles (SongModel having list of other songs) to simplify queries and updates.

3. Manual linking as source of truth

Users explicitly link renditions.

Auto-suggestions may assist but should never auto-commit.

4. Metadata-driven filtering

Each SongModel stores flags like IsInstrumental, Instrumentation, IsLivePerformance.

Queries filter on these instead of parsing titles repeatedly.

---

Steps / Workflow for Implementation

Step 1: Design the Database Model

Add a MusicalWork entity to represent canonical compositions.

Each SongModel optionally links to a MusicalWork.

Ensure MusicalWork contains a list of all linked renditions (SongModels).

Design optional metadata on renditions for filtering (instrumentation, vocals, live, remix, etc.).

Goal: Maintain a clean one-to-many relationship. Avoid lists of songs inside songs.

---

Step 2: Manual Linking UI

Provide a UI to link a song to an existing work.

Include a “Create New Work” option if no appropriate work exists.

Show all renditions under a work in the UI, with filters (instrumental, live, cover, etc.).

Goal: Users can easily organize songs without creating cycles or redundant links.

---

Step 3: Suggestion / Recommendation System

Implement a suggestion engine that evaluates potential links based on:

Title similarity (normalized, ignoring keywords like “instrumental”, “piano”, “remix”)

Duration proximity

Artist match

Optional: metadata (genre, album)

Provide scoring rather than automatic linking.

UI can present top suggestions for user confirmation.

Goal: Reduce user effort while maintaining accuracy.

---

Step 4: Querying and Filtering

Implement efficient queries for:

All renditions of a song

Instrumental only

Live only

Specific instrumentation (piano, cello, etc.)

Ensure queries are Realm-friendly and avoid traversing complex cycles.

Goal: Fast, predictable retrieval of related songs for UI features.

---

Step 5: Analytics / Metadata Integration

Leverage existing SongModel fields:

Play count, favorite count, BPM, genre, etc.

Allow “Work-level” analytics by aggregating metrics across renditions.

Goal: Features like “Most popular rendition”, “Instrumental versions trending”, etc.

---

Step 6: Migration Strategy

For existing songs:

Provide a manual linking flow initially.

Optionally run heuristic suggestions for likely matches based on TitleDurationKey.

Ensure no data is lost and existing relationships remain intact.

Goal: Smooth transition without breaking current library data.

---

Step 7: UI/UX Considerations

Present renditions under a single work in lists or now-playing UI.

Clearly indicate rendition type (instrumental, vocal, live, etc.).

Allow users to filter or jump to other renditions.

Avoid overcomplicated graphs; keep parent-child simple.

Goal: Intuitive interface with minimal cognitive load.

---

Step 8: Enhancements

Implement merge suggestions for works automatically.

Allow users to tag renditions (e.g., “cover”, “remix”) to enrich metadata. With a dedicated UI

Integrate with recommendation engines (playlists, shuffle variants).

Consider analytics on listening habits per work vs per rendition.

---

Expected Benefits

1. Clean, maintainable DB structure.

2. Efficient retrieval of all renditions for UI or analytics.

3. Avoid duplication, cycles, and complex relationships.

4. User-driven linking ensures correctness.

5. Potential for automated or semi-automated suggestions in future.

References / Inspiration

Namida, Retro: Manual linking of ins...

• Fixes Musical Work Linking and Rendition Management #348

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.