yellowjacket/.planning/research/FEATURES.md

# Feature Landscape: v1.1 Features & Extensibility

**Domain:** Desktop music player — new capabilities milestone
**Researched:** 2026-03-06
**Confidence:** HIGH (grounded in codebase analysis, official documentation, established desktop music player patterns)

---

## Overview

This research covers 8 feature areas for YellowJacket v1.1: tag editing, scan cancellation, smart playlists, customizable keyboard shortcuts, gapless playback + crossfade, MusicBrainz browser, layout customization, and plugin system. Each is categorized as table stakes, differentiator, or anti-feature relative to the desktop music player domain.

---

## 1. Tag Editing

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Edit title, artist, album, genre, year, track number | Every music manager (MusicBee, foobar2000, Clementine, Strawberry) supports this. Users expect to correct metadata without leaving the app. | MEDIUM | Existing metadata extraction pipeline, new tag writing libraries |
| Edit single track | Right-click → edit properties is the universal pattern | LOW | Tag writing backend |
| Batch edit multiple tracks | Select multiple → edit shared fields (e.g., set all to same album). This is the primary workflow for fixing album imports. | MEDIUM | Single-track editing must work first |
| Write changes to actual audio files | Tags must persist to the file on disk, not just the DB. Users expect changes to survive re-imports and transfers to other players. | MEDIUM | Tag writing libraries (format-specific) |
| Update DB after tag write | After writing tags to file, the DB must reflect the new metadata without requiring a full rescan. | LOW | Existing DB update queries |
| Cover art assignment | Set/replace embedded cover art from an image file | MEDIUM | Image handling + tag writing |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| Undo/redo for tag edits | Safety net — rare in music players, very valued when present | HIGH | Requires edit history tracking |
| Auto-capitalize/clean tag values | Consistent library appearance with minimal effort | LOW | String utilities |
| Filename-to-tag inference | Parse "Artist - Title.mp3" patterns to pre-fill fields | MEDIUM | Regex/pattern engine |
| Tag-to-filename rename | Rename files based on tag template (e.g., "%artist% - %title%.%ext%") | HIGH | File system operations, template engine |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Auto-tag from online DB in tag editor | Conflates two features — tag editing and metadata lookup. MusicBrainz browser is the separate feature for this. | Keep tag editing purely manual; MusicBrainz browser is the lookup tool |
| Destructive batch operations without confirmation | Mass edits can corrupt a library. | Always show preview/confirmation dialog for batch edits |
| Writing tags during playback of that file | File locking conflicts on Windows; potential corruption on any OS | Queue the write for after playback stops, or copy-on-write |

### Implementation Notes

**Tag writing requires format-specific libraries (the existing `dhowden/tag` is read-only):**

- **MP3 (ID3v2):** `github.com/bogem/id3v2/v2` — mature, pure Go, supports ID3v2.3/2.4 read+write, handles text frames, pictures, comments. Confirmed: `tag.Open()` → `tag.SetArtist()` → `tag.Save()` pattern. v2.1.4 is current.
- **FLAC (Vorbis Comments):** `github.com/go-flac/go-flac` + `github.com/go-flac/flacvorbis` — parse FLAC file, modify vorbis comment metadata blocks, save back. Confirmed: `flac.ParseFile()` → modify `Meta` slice → `f.Save()`. v1.0.0/v0.2.0 current (v2 exists).
- **OGG Vorbis:** No mature pure-Go write library exists. Options: (a) skip OGG tag writing initially, (b) use `go-flac/flacvorbis`-style approach with raw vorbis comment manipulation if a library surfaces, or (c) shell out to `vorbiscomment` CLI tool.
- **WAV:** WAV metadata (INFO chunks, ID3 headers) is rarely edited. Skip for v1.1.

**Critical constraint:** The existing `dhowden/tag` library is read-only. Tag writing is a completely separate code path requiring new dependencies. Tag reading continues through `dhowden/tag`; writing uses format-specific libraries.

**DB sync pattern:** After writing tags to file, update the specific DB rows rather than triggering a full rescan. Extract the new metadata from the written file (or trust the values just written), update the `recordings`, `artists`, `release_groups`, and `audio_files` tables, then emit a `TrackMetadataChanged` event to sync the frontend.

---

## 2. Scan Cancellation

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Cancel button during scan | Large libraries take minutes to scan. Users expect to be able to stop a scan in progress. Every file manager and media player with scanning provides this. | LOW | Existing scan pipeline with `context.Context` |
| Graceful stop (don't corrupt DB) | Cancellation must not leave the DB in an inconsistent state. Complete in-flight transactions, skip remaining files. | LOW | Existing transaction batching |
| Scan progress reporting | Users need to see what's happening — "Processing 340/2000 files" — to decide whether to wait or cancel. | LOW | Existing `ScanProgress` event (already partially implemented) |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| Pause and resume scan | Stop temporarily, resume later without re-scanning already-processed files | HIGH | Would need scan state persistence |
| Background scan with low priority | Scan without impacting playback or UI responsiveness | LOW | Already partially handled by worker pool concurrency tuning |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Immediate hard kill (kill goroutines) | Data corruption risk — partial writes, broken entity caches | Use context cancellation for cooperative shutdown |
| Auto-cancel on any error | Users want the scan to continue past individual file failures | Continue scanning, accumulate warnings (already the pattern) |

### Implementation Notes

**The existing scan pipeline already uses `context.Context` — `l.ctx` is available throughout the scan.** The implementation pattern is straightforward:

1. Create a cancellable context: `scanCtx, cancelScan := context.WithCancel(l.ctx)`
2. Store `cancelScan` so the frontend can trigger it via a Wails binding (e.g., `Library.CancelScan()`)
3. Check `scanCtx.Done()` in the filesystem walk loop, the worker pool dispatch, and the DB writer
4. On cancellation, the `errgroup` returns `context.Canceled`, which is caught and treated as a clean stop
5. Emit `LibraryScanCancelled` event (distinct from `LibraryScanComplete`)

**Key insight:** The existing scan already uses `errgroup` which respects context cancellation. The DB writer goroutine processes whatever is in its batch channel, so in-flight batches complete cleanly. The only new code needed is: (a) storing/exposing the cancel function, (b) checking context in the walk loop, (c) a new event for cancellation.

**Complexity is LOW** because the architecture already supports this pattern. The scan pipeline's multi-phase design means cancellation at any phase is naturally bounded.

---

## 3. Smart Playlists

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Filter by genre | "All Jazz tracks" — the most basic smart playlist rule | LOW | Existing genre data in DB |
| Filter by year/year range | "Tracks from 1990-1999" | LOW | Existing year field in DB |
| Filter by artist | "All tracks by Artist X" | LOW | Existing artist data |
| Combine multiple rules (AND) | "Jazz tracks from the 1990s" — users expect to stack filters | MEDIUM | Rule evaluation engine |
| Auto-update when library changes | Smart playlists should refresh when tracks are added/removed. This is the defining feature vs. manual playlists. | MEDIUM | Event subscription to library changes |
| Name and save smart playlists | Persist rule definitions, show in sidebar alongside regular playlists | LOW | New DB table for rule definitions |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| Filter by play count | "Most played" / "Never played" — requires play count tracking (not currently implemented) | MEDIUM | New `play_count` column or table |
| Filter by date added | "Recently added" — very popular smart playlist | LOW | Existing file modification time or new `added_at` column |
| Filter by rating | Requires rating system (not currently implemented) | MEDIUM | New rating feature |
| OR logic and nested groups | "(Genre=Jazz OR Genre=Blues) AND Year>1980" — powerful but complex UI | HIGH | Recursive rule evaluation, complex UI builder |
| Random/limit results | "Random 50 Jazz tracks" — playlist-as-radio | LOW | SQL `ORDER BY RANDOM() LIMIT N` |
| Sort order in rules | "Newest first" / "Alphabetical by artist" | LOW | SQL `ORDER BY` clause |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Full SQL WHERE clause as input | Exposes DB internals, injection risk, terrible UX | Structured rule builder with defined fields and operators |
| Complex nested boolean logic in v1 | Overwhelms users, complex UI, rarely used | Start with flat AND rules; add OR/nesting later if demanded |
| Real-time updating during playback | Unnecessary overhead — smart playlists don't need sub-second freshness | Refresh on library scan completion and on explicit refresh |

### Implementation Notes

**Rule model — keep it simple for v1:**

```
SmartPlaylistRule {
  Field:    "genre" | "year" | "artist" | "album" | "title" | "date_added"
  Operator: "equals" | "not_equals" | "contains" | "greater_than" | "less_than" | "between"
  Value:    string (or string pair for "between")
}

SmartPlaylist {
  ID:        int64
  Name:      string
  Rules:     []SmartPlaylistRule  // all ANDed together
  SortField: string (optional)
  SortOrder: "asc" | "desc"
  Limit:     int (0 = unlimited)
}
```

**Storage:** New `smart_playlists` table (id, name, rules_json, sort_field, sort_order, limit_count) with rules stored as JSON in a TEXT column. This avoids a complex relational schema for rules and is trivially extensible.

**Query generation:** Each rule maps to a SQL WHERE clause fragment. Rules are joined with AND. The existing `track_metadata` VIEW provides all the needed columns for filtering. Generated SQL uses parameterized queries (NOT string concatenation) to prevent injection.

**Refresh strategy:** Smart playlists evaluate lazily — results are computed on access and cached. Cache is invalidated on `LibraryScanComplete` events. This avoids expensive re-evaluation on every library change.

**Depends on:** Existing `track_metadata` VIEW, playlist sidebar UI, event system.

---

## 4. Customizable Keyboard Shortcuts

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Play/pause hotkey | Space bar is universal; must work | LOW | Existing player controls |
| Next/previous track | Arrow keys or media key equivalents | LOW | Existing queue navigation |
| Volume up/down | Standard audio app functionality | LOW | Existing volume control |
| Mute toggle | Expected in any audio application | LOW | Existing mute functionality |
| Search focus | Ctrl+F or / to focus search — standard in any list-heavy app | LOW | Existing search bar |
| Default keybindings that work out of box | Users shouldn't have to configure anything to get basic shortcuts | LOW | Hardcoded defaults with override capability |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| Full customization UI | Visual keybinding editor with conflict detection | MEDIUM | Settings page extension |
| Import/export keybindings | Share/backup custom configs | LOW | TOML serialization (already used for config) |
| Scoped shortcuts (global vs. component-specific) | Different bindings when focus is in search vs. track list | MEDIUM | Focus tracking |
| "When focused" context awareness | Arrows navigate track list when it's focused, but control volume when player is focused | MEDIUM | Component focus management |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Global OS-level hotkeys (outside app window) | Platform-specific, conflicts with OS shortcuts, security concerns on Wayland | App-scoped shortcuts only; MPRIS2 handles media keys |
| Vim-mode or complex modal keybindings | Niche appeal, confusing for 99% of users | Simple single/modifier key combos (Ctrl+X, Shift+X) |
| Shortcut for every possible action | Overwhelming configuration UI | Cover the 10-15 most common actions; rest accessible via menus |

### Implementation Notes

**Architecture — event-driven, backend-aware:**

The shortcut system has two layers:
1. **Frontend key listener:** Captures keyboard events at the document level, maps keystrokes to action names using a binding table
2. **Action dispatch:** Frontend calls the appropriate Wails binding or emits a frontend event for UI-only actions

**Binding table structure:**

```typescript
interface KeyBinding {
  action: string;        // "play_pause", "next_track", "volume_up", etc.
  key: string;           // "Space", "ArrowRight", etc. (KeyboardEvent.key)
  modifiers: string[];   // ["ctrl"], ["shift"], ["ctrl", "shift"], []
  scope?: string;        // "global" | "tracklist" | "queue" (optional, default "global")
}
```

**Storage:** Add `[Shortcuts]` section to TOML config. Default bindings are hardcoded; user overrides merge on top. Config change emits `ShortcutConfigChanged` event.

**Conflict detection:** When user changes a binding, check for conflicts within the same scope. Show warning if two actions share the same keystroke.

**Default bindings (the 12 essentials):**

| Action | Default Key | Scope |
|--------|-------------|-------|
| Play/Pause | Space | global |
| Stop | . (period) | global |
| Next Track | Ctrl+Right | global |
| Previous Track | Ctrl+Left | global |
| Volume Up | Ctrl+Up | global |
| Volume Down | Ctrl+Down | global |
| Mute | M | global |
| Search Focus | Ctrl+F | global |
| Toggle Queue | Q | global |
| Toggle Shuffle | S | global |
| Toggle Repeat | R | global |
| Select All (track list) | Ctrl+A | tracklist |

**Key insight:** Keyboard shortcuts must NOT interfere with text input. When a text input or textarea has focus, the shortcut system must be disabled (except for Escape to blur). This is the #1 pitfall in keyboard shortcut implementations.

---

## 5. Gapless Playback + Crossfade

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Gapless playback (no silence between tracks) | Expected by any serious music listener. Albums are meant to flow. Strawberry, foobar2000, Deadbeef, Audacious all support this. | HIGH | Fundamental change to audio pipeline |
| Crossfade setting (on/off, duration) | Standard feature in every modern music player. Even basic mobile players have this. | MEDIUM | Gapless infrastructure + mixer |
| Crossfade duration control | Users expect 1-10 second configurable fade | LOW | UI slider + config storage |
| Gapless without crossfade (default) | Pure gapless (no overlap) should be the default. Crossfade is opt-in. | HIGH | Pre-decode/buffer next track |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| Per-album gapless (auto-detect live albums) | Disable crossfade within albums, enable between albums | MEDIUM | Album boundary detection in queue |
| ReplayGain normalization | Consistent volume across tracks from different sources | HIGH | ReplayGain tag parsing + volume adjustment |
| Fade-in on play, fade-out on pause | Smoother start/stop experience | LOW | Volume envelope on play/pause |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| DSP effects chain (equalizer, reverb, etc.) | Scope explosion — not part of gapless/crossfade | Defer to plugin system if ever needed |
| Crossfade for all transitions (including manual skip) | Crossfade on skip feels sluggish | Only crossfade on auto-advance; manual skip is instant |
| Pre-loading entire tracks into memory | Memory explosion with FLAC files (50-100MB per track) | Buffer only the crossfade overlap region (last/first N seconds) |

### Implementation Notes

**This is the highest-complexity feature in v1.1.** The current audio pipeline plays one track at a time with a single streamer chain. Gapless playback requires pre-decoding the next track and seamlessly transitioning.

**Current pipeline:** `file → decode → resample → BufferedStreamer → Ctrl → Volume → Speaker`

**Gapless pipeline (conceptual):**
1. When current track is N seconds from ending, pre-load next track's decoder + resampler
2. For pure gapless: use `beep.Seq()` to chain current and next streamer — but Seq doesn't support the pre-decode timing
3. For crossfade: use `beep.Mixer` to overlap the fade-out of current with fade-in of next

**beep library support:**
- `beep.Mixer` — adds/mixes multiple streamers. This is the foundation for crossfade.
- `beep.Seq()` — sequences streamers end-to-end. Foundation for gapless without crossfade.
- `effects.Volume` — volume control already used; can create fade curves by adjusting volume over time.
- `beep.Take()` — extract N samples from a streamer. Useful for defining crossfade regions.

**Architecture change required:**
- The `Player` must manage TWO streamer chains simultaneously during crossfade
- A `TransitionManager` or equivalent coordinates pre-loading the next track
- The `playbackFinishedHandler` (callback from beep when track ends) must trigger next-track pre-loading rather than waiting for the callback
- The `Queue` must expose a "peek next" capability (already has `tracks` and `currentIndex`)

**Crossfade implementation sketch:**
```
[Track A ~~~~~~~~ fade-out]
                [fade-in ~~~~~~~~ Track B]
                |-- overlap (N seconds) --|
```
- Track A's volume ramps from 1.0 → 0.0 over N seconds
- Track B's volume ramps from 0.0 → 1.0 over N seconds
- Both feed into a `beep.Mixer` during the overlap period
- After overlap, Track A is closed, Track B continues alone

**Config addition:** `[Playback]` section with `GaplessEnabled` (bool, default true), `CrossfadeEnabled` (bool, default false), `CrossfadeDurationMs` (int, default 3000, range 500-10000).

**Critical constraint:** The beep `speaker.Play()` can only be called once; the speaker's mixer is the root. All track management must happen within the streamer chain that the speaker is already playing. This means using a persistent `beep.Mixer` as the root streamer, adding/removing track streamers from it.

---

## 6. MusicBrainz Browser

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Search artists by name | The entry point — user types artist name, gets results | MEDIUM | MusicBrainz API integration, HTTP client |
| View artist discography (release groups) | Browse albums/EPs/singles by an artist | MEDIUM | API browse: release-groups by artist |
| View album track listing | See what tracks are on a release | MEDIUM | API lookup: release with recordings |
| View album editions (releases within a release group) | Different pressings, reissues, deluxe editions | MEDIUM | API browse: releases by release-group |
| Rate limiting compliance | MusicBrainz requires max 1 request/second with meaningful User-Agent | LOW | HTTP rate limiter, User-Agent header |
| Offline-safe (read-only, no writes) | Read-only browsing — no MusicBrainz account needed | LOW | No authentication required for reads |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| Link local tracks to MusicBrainz recordings | Associate library tracks with MBIDs for definitive identity | HIGH | Matching algorithm, DB schema changes |
| Show cover art from Cover Art Archive | Display album art from MusicBrainz's linked image archive | MEDIUM | coverartarchive.org API |
| Cache API responses locally | Avoid re-fetching on every browse session | MEDIUM | SQLite cache table with TTL |
| Search recordings | Find specific songs across all releases | LOW | MusicBrainz recording search API |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Auto-tag from MusicBrainz | This is Picard's domain — extremely complex matching logic | Read-only browsing only. Users can manually apply info from browse to tag editor. |
| Write data to MusicBrainz | Requires OAuth, community guidelines compliance, edit approval | Strictly read-only |
| Download/stream from MusicBrainz | MusicBrainz is a metadata database, not a music source | Display metadata only |
| Background MusicBrainz scanning of entire library | Rate limiting makes this impractical (1 req/sec = 3600 tracks/hour max) | On-demand browsing only |

### Implementation Notes

**MusicBrainz API:** REST API at `https://musicbrainz.org/ws/2/`. JSON format via `fmt=json` parameter. No API key required, but must set meaningful User-Agent header: `YellowJacket/<version> (contact-url-or-email)`.

**Rate limiting:** Strict 1 request/second. Implement with a `time.Ticker`-based rate limiter in the Go backend. All API calls go through a single rate-limited HTTP client.

**Go libraries available:**
- `github.com/michiwend/gomusicbrainz` — Go client, but may be outdated
- `go.uploadedlobster.com/musicbrainzws2` — another Go client on SourceHut
- **Recommended: Build a thin HTTP client** — the API is simple REST/JSON. A custom client with rate limiting, User-Agent, and JSON parsing is ~200 lines and avoids third-party dependency risk.

**API patterns needed for read-only browsing:**
1. **Search artist:** `GET /ws/2/artist?query=<name>&fmt=json&limit=25`
2. **Artist discography:** `GET /ws/2/release-group?artist=<mbid>&fmt=json&limit=100&inc=artist-credits`
3. **Release group releases:** `GET /ws/2/release?release-group=<mbid>&fmt=json&inc=media+recordings`
4. **Release track listing:** `GET /ws/2/release/<mbid>?fmt=json&inc=recordings+media+artist-credits`

**Frontend architecture:** New view (`musicbrainz-browser` component) accessible from sidebar. Search bar, results list, detail panels for artist/album/release. Navigation is drill-down: search → artist → release group → release → tracks.

**Caching strategy:** Cache API responses in SQLite (`mb_cache` table: url, response_json, fetched_at). TTL of 24 hours for search results, 7 days for entity lookups (MusicBrainz data changes infrequently). Cache reduces API calls and improves responsiveness.

**This is YellowJacket's first network feature** — the app is currently fully offline. Need to handle: network errors gracefully, timeout configuration, offline mode (show cached data), user notification of network status.

---

## 7. Layout Customization System

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Resizable panels (sidebar, queue, main) | Basic expectation in any multi-panel desktop app. Users want wider sidebar or hidden queue. | MEDIUM | CSS grid/flexbox with drag handles |
| Show/hide queue panel | Already partially implemented (queue toggle button exists) | LOW | Existing queue panel toggle |
| Show/hide sidebar sections | Collapse navigation sections user doesn't need | LOW | Sidebar configuration |
| Persist layout across restarts | Layout changes must survive app restart | LOW | TOML config section |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| Section-based component placement (MusicBee-style) | Users choose what goes where — put album art in sidebar, now-playing at top, etc. This is MusicBee's signature feature. | HIGH | Component registry, layout engine, size constraints |
| Component size constraints | Components declare min/max sizes; layout engine respects constraints | MEDIUM | Component metadata system |
| Layout presets | "Compact", "Full", "Mini player" — quick switch between configurations | MEDIUM | Preset definitions + switch mechanism |
| Detachable panels | Pop out queue or now-playing to separate window | HIGH | Wails multi-window support (limited in v2) |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Free-form drag-and-drop layout | Overwhelming complexity, hard to make look good | Section-based: defined slots with selectable components |
| CSS theme editor | Users don't want to write CSS | Extend existing theme system (accent color, background shade) |
| Mobile-responsive layout | This is a desktop app with fixed minimum size | Optimize for 1024x768 minimum |

### Implementation Notes

**MusicBee-style layout means section-based composition:**

The UI is divided into named sections (slots):
- `header` (top bar)
- `sidebar` (left panel)
- `main` (center content area)
- `footer` (bottom bar — now playing + player controls)
- `right-panel` (queue panel or other content)

Each section has a list of components it can host. Components declare their size constraints (min width/height). Users configure which component goes in which section via a settings UI.

**Implementation approach:**

1. **Component registry:** Each component registers itself with metadata (name, description, supported sections, min/max size). This is a TypeScript Map, not a plugin system yet.
2. **Layout configuration:** Stored in TOML config under `[Layout]` section. Maps section names to component names.
3. **Layout renderer:** A root `<app-layout>` component reads config and instantiates the right components in the right sections using dynamic imports.
4. **Resize handles:** CSS resize or custom drag handles on section boundaries. Store widths/heights as percentages in config.

**Start simple for v1.1:**
- Phase 1: Resizable panels (sidebar width, queue width) with drag handles + persistence
- Phase 2: Show/hide sections + layout presets
- Phase 3: Component-in-section customization (the full MusicBee-style system)

The full section-based system is the v1.1 "foundation" — functional but not complete.

**Depends on:** Config system (TOML), existing component architecture, CSS grid layout.

---

## 8. Plugin System

### Table Stakes

| Feature | Why Expected | Complexity | Dependencies |
|---------|--------------|------------|--------------|
| Defined plugin API (what plugins can do) | Without clear API boundaries, plugins break on every update | HIGH | API design + stability commitment |
| Plugin loading/unloading | Install/remove plugins without rebuilding the app | HIGH | Dynamic loading mechanism |
| Plugin configuration | Plugins need their own settings that persist | MEDIUM | Extend config system |
| Plugin isolation (one plugin crash doesn't kill app) | Critical for stability | HIGH | Error boundaries, sandboxing |

### Differentiators

| Feature | Value Proposition | Complexity | Dependencies |
|---------|-------------------|------------|--------------|
| UI component plugins (custom panels, visualizations) | Plugins can add new views to the layout system | HIGH | Layout customization system + component registry |
| Backend hook plugins (custom metadata sources, scrobblers) | Plugins can intercept/extend backend operations | HIGH | Hook system in Go backend |
| Plugin marketplace/registry | Discover and install plugins | HIGH | External infrastructure |
| TypeScript/JavaScript plugin runtime | Lowest barrier to entry for plugin authors | MEDIUM | Webview already runs JS |

### Anti-Features

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Go plugin system (`plugin` package) | Linux-only, version-fragile, build-tag sensitive, widely considered broken | Use process-based or embedded scripting approach |
| Full filesystem access for plugins | Security nightmare | Sandboxed API with explicit permissions |
| Plugin binary distribution | Build reproducibility, platform issues | Source-based distribution (TypeScript/JS bundles) |
| Network access for plugins without user consent | Privacy concern | Require explicit network permission declaration |

### Implementation Notes

**Plugin systems in Go desktop apps are notoriously difficult.** The `plugin` package is Linux-only and requires exact build-tag matching. Wails v2 doesn't have a plugin framework.

**Recommended approach for v1.1 "foundation":**

1. **Frontend-first plugins (TypeScript):**
   - Plugins are JS/TS bundles loaded dynamically into the webview
   - They register with the component registry (layout system) to add UI
   - They access backend data through the existing Wails binding layer
   - Isolation via Shadow DOM for UI, try/catch for errors

2. **Backend hooks (Go):**
   - Define hook points as interfaces: `OnTrackPlay`, `OnLibraryScan`, `OnMetadataChange`, etc.
   - Internal Go "plugins" implement these interfaces
   - For v1.1, hooks are compile-time (not dynamic) — the plugin system defines the API, but plugins are compiled in
   - Dynamic loading deferred to future (hashicorp/go-plugin RPC, or WASM)

3. **Plugin manifest:**
   ```json
   {
     "name": "my-plugin",
     "version": "1.0.0",
     "description": "Does a thing",
     "entry": "index.js",
     "hooks": ["onTrackPlay", "onLibraryScan"],
     "ui": [{"component": "my-panel", "sections": ["sidebar", "right-panel"]}],
     "permissions": ["network"]
   }
   ```

4. **Plugin directory:** `~/.config/yellowjacket/plugins/<name>/` containing manifest + JS bundle

**v1.1 scope should be the API definition and loading mechanism** — not a full marketplace. "Working foundation" means: plugins can be loaded, they can register UI components, they can subscribe to backend events. The API surface is deliberately small and stable.

**Depends on:** Layout customization system (for UI plugins), event system (for hook subscriptions), config system (for plugin settings).

---

## Feature Dependencies

```
Scan Cancellation ──── (standalone, no dependencies)
     │
Tag Editing ────────── (standalone, needs new libraries)
     │
Smart Playlists ────── depends on: existing DB/track_metadata VIEW
     │
Keyboard Shortcuts ─── (standalone, frontend-primary)
     │
Gapless + Crossfade ── depends on: audio pipeline refactor
     │
MusicBrainz Browser ── depends on: HTTP client (new), network handling (new)
     │
Layout Customization ── depends on: component registry (new)
     │
Plugin System ──────── depends on: Layout Customization, Event system, Config system
```

**Dependency ordering (what blocks what):**
1. **Nothing blocks:** Scan cancellation, tag editing, keyboard shortcuts, smart playlists, MusicBrainz browser
2. **Layout blocks plugins:** Plugin UI registration needs the layout component registry
3. **Gapless is self-contained** but is the highest-risk change (audio pipeline)

---

## MVP Recommendation

### Build First (low risk, high value, unblocked)
1. **Scan cancellation** — lowest complexity, immediate UX win, architecture already supports it
2. **Keyboard shortcuts** — low complexity, massive usability improvement, no backend changes
3. **Smart playlists** — medium complexity, high value, builds on existing DB infrastructure

### Build Second (medium risk, foundational)
4. **Tag editing** — medium complexity, requires new dependencies, needed before MusicBrainz becomes useful
5. **MusicBrainz browser** — medium complexity, first network feature, independent of others
6. **Layout customization** — medium-high complexity, needed before plugins

### Build Last (high risk, high complexity)
7. **Gapless playback + crossfade** — highest complexity, fundamental audio pipeline change, can ship independently
8. **Plugin system** — highest complexity, depends on layout system, explicitly a "foundation" for v1.1

### Defer (explicitly)
- Tag-to-filename rename
- Undo/redo for tag edits
- Play count tracking (needed for some smart playlist rules)
- Rating system
- Plugin marketplace
- Dynamic Go plugin loading
- Detachable panels (Wails v2 limitation)

---

## Sources

- MusicBrainz API documentation: https://musicbrainz.org/doc/MusicBrainz_API (HIGH confidence — official docs, verified 2026-03-06)
- MusicBrainz rate limiting: https://musicbrainz.org/doc/MusicBrainz_API/Rate_Limiting (HIGH confidence — official docs)
- `github.com/bogem/id3v2/v2` v2.1.4: https://pkg.go.dev/github.com/bogem/id3v2/v2 (HIGH confidence — official pkg.go.dev)
- `github.com/go-flac/go-flac` v1.0.0: https://pkg.go.dev/github.com/go-flac/go-flac (HIGH confidence — official pkg.go.dev)
- `github.com/go-flac/flacvorbis` v0.2.0: https://pkg.go.dev/github.com/go-flac/flacvorbis (HIGH confidence — official pkg.go.dev)
- `github.com/gopxl/beep/v2` v2.1.1: https://pkg.go.dev/github.com/gopxl/beep/v2 (HIGH confidence — official pkg.go.dev, confirms Mixer, Seq, Loop2, effects)
- YellowJacket codebase analysis: `.planning/codebase/` (HIGH confidence — direct code inspection)
- Desktop music player patterns: foobar2000, MusicBee, Strawberry, Deadbeef, Audacious (MEDIUM confidence — training data knowledge of established players)