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
74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
# 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:
|
|
1. Show confirmation dialog
|
|
2. Remove tracks from DB (or mark as missing)
|
|
3. Handle playlist references (delete, mark phantom, or leave as-is)
|
|
4. 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.
|