yonlu
cdf8bff01a
- Rename milestone from 'Features & Extensibility' to 'Multi-Library Support' - Replace old phases 10-14 (TAG/SMRT/GAP/MB/LAYOUT/PLUG) with 20 multi-library requirements (LIB/LSCAN/VIEW/PLAY/DATA) - Move deferred features to Future Requirements - Update research files with multi-library research (Stack, Features, Architecture, Pitfalls) - Architecture: hybrid model (library_id on audio_files only), libraries in DB, sequential scanning, phantom tracks
3.2 KiB
Features Research: Multi-Library Support
Researched: 2026-03-08 Confidence: HIGH
How Mature Players Handle Multiple Libraries
| Player | Model | Libraries Separate? | Cross-Library Playlists? |
|---|---|---|---|
| foobar2000 | Multiple folders, one merged library | No — all folders merge | N/A (one library) |
| MusicBee | Multiple folders per library, separate library databases | Yes (separate DBs) | No |
| Plex | Separate typed libraries, multiple folders each | Yes (fully isolated) | No |
| Jellyfin | Virtual collections with multiple paths | Yes | No |
| Navidrome | Named libraries with user access control | Yes (with multi-select merge) | Yes |
| Roon | Watched folders, one unified library | No — all merge | N/A (one library) |
Desktop Player Pattern (foobar2000, Roon)
All folders contribute to one unified library. No folder-level filtering in default UI. User never thinks about "which folder."
Server Pattern (Plex, Jellyfin, Navidrome)
Separate libraries with access control. More suited to multi-user server apps.
YellowJacket Fit
Desktop player = merged by default, with optional filter. Follows foobar2000/Roon pattern but adds Navidrome-style library selector for power users.
Feature Classification
Table Stakes (Must Have)
| Feature | Complexity | Dependencies |
|---|---|---|
| Add multiple watched folders | Low | Config to DB migration |
| Unified merged view (default) | Medium | All browse views, search aggregate |
| Per-folder independent scan | Medium | Scan pipeline scoping |
| Remove folder without data loss | Low | Phantom tracks for playlists |
| Folder status indicators | Low | Scan event system |
| Graceful offline handling | Medium | Guard orphan cleanup |
| Existing playlists unaffected | Low | File-path references already work |
Differentiators (Nice to Have)
| Feature | Complexity | Dependencies |
|---|---|---|
| Filter/narrow by source folder | Medium | UI filter chip, query-level filtering |
| Named libraries | Low | DB stores name + path |
| Per-folder scan concurrency | Low | Extend existing ScanConcurrency per library |
| Folder health dashboard | Medium | Aggregate scan metrics |
Anti-Features (Do NOT Build)
| Anti-Feature | Why Avoid |
|---|---|
| Separate databases per library | Breaks unified browse, doubles query logic |
| User/access control per library | Desktop app is single-user |
| Auto-merge/deduplicate across folders | Complex, error-prone, unexpected |
| Library-specific settings/themes | Over-engineering |
Library Removal Patterns
All players that support library removal:
- Show confirmation dialog
- Remove tracks from DB (or mark as missing)
- Handle playlist references (delete, mark phantom, or leave as-is)
- Don't delete files from disk
YellowJacket approach: Phantom tracks (preserving metadata) for playlists. Queue tracks cascade-deleted (ephemeral). Orphan cleanup for shared entities via reference counting.
Offline Handling
Universal pattern: Don't delete tracks when source goes offline. Mark as unavailable. Auto-recover on next scan when source returns. Never auto-delete on temporary unavailability.