Add Emby provider (#207)

* Add Emby provider

Adds a new provider for Emby Media Server, mirroring the Jellyfin
provider but with Emby-specific API behaviour:

- Authorization header uses the 'Emby' scheme (Jellyfin uses 'MediaBrowser')
- Ping uses GET /System/Info — Emby API keys are server-level and return
  500 on /Users/Me, which Jellyfin's Ping calls
- UserID() falls back from /Users/Me to GET /Users for API key auth,
  preferring a user whose name matches the configured username
- Full test coverage: client (MusicLibraries, Albums, Tracks, StreamURL,
  password auth, NowPlaying, Scrobble, Ping, API key user fallback) and
  provider (Name, Playlists, Tracks, CanReportPlayback)

Also adds:
- 'E' keybinding to switch to Emby from anywhere in the UI
- cliamp setup wizard support (token / username+password picker)
- [emby] config section with same fields as [jellyfin]
- docs/emby.md, updates to docs/cli.md, docs/configuration.md,
  docs/keybindings.md, config.toml.example, and site/index.html

* Address CodeRabbit review: emby provider fixes

- postJSON: wrap json.Marshal error with path context
- UserID: return explicit error when configured user name not found in /Users
- AlbumList: clamp negative offset to 0
- Playlists: return copy of cache slice to prevent external mutation
- setup.go: wrap Emby ping error with "emby: validation:" prefix
- docs/emby.md: fix Quick start blurb (references /System/Info, not /Users/Me)
- site/index.html: add E key to Provider Browser quick-switch row

* Convert new Emby tests to table-driven style

* Wrap all bare errors in client.go with operation context

* Wrap provider-level browse errors with operation context

* Clarify that 'user' affects API key auth as well as password login

* Add optional username field to Emby API key setup mode

* Fix Emby empty-state hint to cover both auth modes

* Tweak Emby empty-state hint wording

* Fix Emby empty-state hint wording

* Return defensive copies from Playlists/Tracks cache; fix docs em dash

* Add emby to --provider flag valid values

* emby: drop double-prefixed errors and align cache returns with Jellyfin

Provider methods were wrapping client errors with `fmt.Errorf("emby: <op>: %w", err)`,
but client.go already prefixes every error with `emby: <path>:`. End-users saw
messages like `emby: artists: emby: /Items: http status 401`. Drop the redundant
package prefix from provider.go; keep the operation context.

Also drop the per-call defensive copies (`copyTracks`, the playlist slice
clone). The existing Jellyfin provider — which shares this same caching shape —
returns cached slices and maps directly, and no consumer in ui/model/ mutates
the returned tracks. Aliasing through `ProviderMeta` is theoretically possible
but would be a caller bug to fix at the caller, not papered over per-provider.
Aligning Emby with the Jellyfin pattern keeps the two providers behaviorally
identical and removes per-fetch allocations.

---------

Co-authored-by: Sam Hassell <yeehah@protonmail.com>
Co-authored-by: bjarneo <bjarneo@users.noreply.github.com>
Co-authored-by: Bjarne Øverli <bjarne.oeverli@gmail.com>

Author: 3 people

cmd/setup.go

@@ -24,6 +24,7 @@ import (
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
 
+	"cliamp/external/emby"
 	"cliamp/external/jellyfin"
 	"cliamp/external/navidrome"
 	"cliamp/external/plex"
@@ -85,6 +86,7 @@ type pickerOption struct {
 // leading underscore distinguishes them from TOML field names.
 const (
 	keyJellyfinAuth = "_auth"
+	keyEmbyAuth     = "_emby_auth"
 	keyYTMusicMode  = "_mode"
 )
 
@@ -177,6 +179,55 @@ func providers() []providerSpec {
 				return strings.Join(lines, "\n")
 			},
 		},
+		{
+			key:     "emby",
+			name:    "Emby",
+			section: "emby",
+			intro: []string{
+				"Authenticate with an API key (Dashboard → API Keys)",
+				"or with your username and password.",
+			},
+			picker: &pickerSpec{
+				key:   keyEmbyAuth,
+				label: "Authentication",
+				options: []pickerOption{
+					{value: "token", label: "API key"},
+					{value: "password", label: "Username + password"},
+				},
+			},
+			fields: []fieldSpec{
+				{key: "url", label: "Server URL", help: "e.g. https://emby.example.com", required: true},
+				{key: "token", label: "API key", required: true, secret: true,
+					onlyIf: func(v map[string]string) bool { return v[keyEmbyAuth] == "token" }},
+				{key: "user", label: "Username (optional)", help: "multi-user servers: picks your account from /Users",
+					onlyIf: func(v map[string]string) bool { return v[keyEmbyAuth] == "token" }},
+				{key: "user", label: "Username", required: true,
+					onlyIf: func(v map[string]string) bool { return v[keyEmbyAuth] == "password" }},
+				{key: "password", label: "Password", required: true, secret: true,
+					onlyIf: func(v map[string]string) bool { return v[keyEmbyAuth] == "password" }},
+			},
+			validate: func(v map[string]string) error {
+				if err := emby.NewClient(v["url"], v["token"], "", v["user"], v["password"]).Ping(); err != nil {
+					return fmt.Errorf("emby: validation: %w", err)
+				}
+				return nil
+			},
+			body: func(v map[string]string) string {
+				lines := []string{fmt.Sprintf("url      = %q", v["url"])}
+				if v[keyEmbyAuth] == "token" {
+					lines = append(lines, fmt.Sprintf("token    = %q", v["token"]))
+					if v["user"] != "" {
+						lines = append(lines, fmt.Sprintf("user     = %q", v["user"]))
+					}
+				} else {
+					lines = append(lines,
+						fmt.Sprintf("user     = %q", v["user"]),
+						fmt.Sprintf("password = %q", v["password"]),
+					)
+				}
+				return strings.Join(lines, "\n")
+			},
+		},
 		{
 			key:     "spotify",
 			name:    "Spotify (Premium)",

cmd/setup_test.go

@@ -97,6 +97,64 @@ func TestPickerSelectionFiltersFields(t *testing.T) {
 	}
 }
 
+// TestEmbyPickerSelectionFiltersFields mirrors TestPickerSelectionFiltersFields
+// for the Emby provider, which uses the same token/password picker shape.
+func TestEmbyPickerSelectionFiltersFields(t *testing.T) {
+	m := newSetupModel()
+
+	embyIdx := -1
+	for i, p := range m.provs {
+		if p.section == "emby" {
+			embyIdx = i
+			break
+		}
+	}
+	if embyIdx < 0 {
+		t.Fatal("emby spec missing")
+	}
+
+	tests := []struct {
+		name         string
+		pickerCursor int
+		wantVisible  []string
+		wantHidden   []string
+	}{
+		{"API key", 0, []string{"url", "token", "user"}, []string{"password"}},
+		{"password", 1, []string{"url", "user", "password"}, []string{"token"}},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			m.menuCursor = embyIdx
+			m.stage = stageMenu
+			m.values = map[string]string{}
+			m.handleKey(keyPress(tea.KeyEnter, "")) // open picker
+			if m.stage != stagePicker {
+				t.Fatalf("stage = %v, want stagePicker", m.stage)
+			}
+			m.pickerCursor = tc.pickerCursor
+			m.handleKey(keyPress(tea.KeyEnter, "")) // select picker option
+			if m.stage != stageForm {
+				t.Fatalf("stage = %v, want stageForm", m.stage)
+			}
+			visible := map[string]bool{}
+			for _, idx := range m.visible {
+				visible[m.provs[embyIdx].fields[idx].key] = true
+			}
+			for _, k := range tc.wantVisible {
+				if !visible[k] {
+					t.Errorf("field %q not visible; got %v", k, visible)
+				}
+			}
+			for _, k := range tc.wantHidden {
+				if visible[k] {
+					t.Errorf("field %q should be hidden; got %v", k, visible)
+				}
+			}
+		})
+	}
+}
+
 // TestRequiredFieldBlocksSubmit ensures pressing Enter on the last field
 // without filling required values produces an error result rather than
 // silently saving.

commands.go

@@ -32,7 +32,7 @@ func buildApp() *cli.Command {
 		&cli.BoolFlag{Name: "no-mono", Usage: "disable mono output"},
 		&cli.BoolFlag{Name: "auto-play", Usage: "start playback immediately"},
 		&cli.BoolFlag{Name: "compact", Usage: "compact mode (80 columns)"},
-		&cli.StringFlag{Name: "provider", Usage: "default provider: radio, navidrome, plex, jellyfin, spotify, soundcloud, yt, youtube, ytmusic"},
+		&cli.StringFlag{Name: "provider", Usage: "default provider: radio, navidrome, plex, jellyfin, emby, spotify, soundcloud, yt, youtube, ytmusic"},
 		&cli.StringFlag{Name: "start-theme", Usage: "UI theme name"},
 		&cli.StringFlag{Name: "visualizer", Usage: "visualizer mode"},
 		&cli.StringFlag{Name: "eq-preset", Usage: "EQ preset name"},
@@ -147,10 +147,10 @@ func overridesFromFlags(c *cli.Command) (config.Overrides, error) {
 	if c.IsSet("provider") {
 		v := strings.ToLower(c.String("provider"))
 		switch v {
-		case "radio", "navidrome", "spotify", "plex", "jellyfin", "soundcloud", "yt", "youtube", "ytmusic":
+		case "radio", "navidrome", "spotify", "plex", "jellyfin", "emby", "soundcloud", "yt", "youtube", "ytmusic":
 			ov.Provider = &v
 		default:
-			return ov, fmt.Errorf("--provider must be radio, navidrome, spotify, plex, jellyfin, soundcloud, yt, youtube, or ytmusic (got %q)", v)
+			return ov, fmt.Errorf("--provider must be radio, navidrome, spotify, plex, jellyfin, emby, soundcloud, yt, youtube, or ytmusic (got %q)", v)
 		}
 	}
 	if c.IsSet("start-theme") {

config.toml.example

@@ -32,7 +32,7 @@ eq_preset = "Flat"
 # Only used when eq_preset is "Custom" or empty
 eq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 
-# Default provider on startup: "radio", "navidrome", "spotify", "plex", "jellyfin", "soundcloud", or a YouTube provider
+# Default provider on startup: "radio", "navidrome", "spotify", "plex", "jellyfin", "emby", "soundcloud", or a YouTube provider
 # provider = "radio"
 
 # Compact mode: cap UI width at 80 columns (default: fluid/full-width)
@@ -95,3 +95,14 @@ eq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 # password = "secret"
 # token = "optional-api-token"
 # user_id = "optional-user-id"
+
+# ---
+# Emby server (optional)
+# Authenticate either with an API key or with your username/password.
+# user_id is optional and is discovered automatically when omitted.
+# [emby]
+# url = "https://emby.example.com"
+# user = "alice"
+# password = "secret"
+# token = "optional-api-key"
+# user_id = "optional-user-id"

config/config.go

@@ -175,6 +175,22 @@ func (j JellyfinConfig) IsSet() bool {
 	return j.URL != "" && (j.Token != "" || (j.User != "" && j.Password != ""))
 }
 
+// EmbyConfig holds credentials for an Emby server.
+// URL is required. Authenticate either with Token, or with User+Password.
+// UserID is optional and can be discovered lazily.
+type EmbyConfig struct {
+	URL      string // e.g. "https://emby.example.com"
+	Token    string // API access token
+	User     string // optional username for password-based login
+	Password string // optional password for password-based login
+	UserID   string // optional user id to skip discovery via /Users/Me
+}
+
+// IsSet reports whether the Emby provider is configured.
+func (e EmbyConfig) IsSet() bool {
+	return e.URL != "" && (e.Token != "" || (e.User != "" && e.Password != ""))
+}
+
 // Config holds user preferences loaded from the config file.
 type Config struct {
 	Volume          float64     // dB, range [-30, +6]
@@ -186,7 +202,7 @@ type Config struct {
 	Speed           float64                      // playback speed ratio: 0.25–2.0 (default 1.0)
 	AutoPlay        bool                         // start playback automatically on launch (radio streams, CLI tracks)
 	SeekStepLarge   int                          // seconds for Shift+Left/Right seek jumps
-	Provider        string                       // default provider: "radio", "navidrome", "spotify", "plex", "jellyfin", "ytmusic" (default "radio")
+	Provider        string                       // default provider: "radio", "navidrome", "spotify", "plex", "jellyfin", "emby", "ytmusic" (default "radio")
 	Theme           string                       // theme name, or "" for ANSI default
 	Visualizer      string                       // visualizer mode name, or "" for default (Bars)
 	SampleRate      int                          // output sample rate: 22050, 44100, 48000, 96000, 192000
@@ -203,6 +219,7 @@ type Config struct {
 	YouTubeMusic    YouTubeMusicConfig           // optional YouTube Music provider
 	Plex            PlexConfig                   // optional Plex Media Server credentials
 	Jellyfin        JellyfinConfig               // optional Jellyfin server credentials
+	Emby            EmbyConfig                   // optional Emby server credentials
 	SoundCloud      SoundCloudConfig             // SoundCloud provider (search always available; user enables browse)
 	Plugins         map[string]map[string]string // per-plugin config from [plugins.*] sections
 	LogLevel        string                       // log level: debug, info, warn, error (default "info")
@@ -355,6 +372,19 @@ func Load() (Config, error) {
 			case "user_id":
 				cfg.Jellyfin.UserID = parseString(val)
 			}
+		case "emby":
+			switch key {
+			case "url":
+				cfg.Emby.URL = parseString(val)
+			case "token":
+				cfg.Emby.Token = parseString(val)
+			case "user":
+				cfg.Emby.User = parseString(val)
+			case "password":
+				cfg.Emby.Password = parseString(val)
+			case "user_id":
+				cfg.Emby.UserID = parseString(val)
+			}
 		default:
 			// Handle [plugins] and [plugins.*] sections.
 			if section == "plugins" || strings.HasPrefix(section, "plugins.") {

docs/cli.md

@@ -98,7 +98,7 @@ CLI flags override config file values for the current session only. They are not
 
 ## Setup wizard
 
-Configure remote providers (Navidrome, Plex, Jellyfin, Spotify, YouTube Music) through a small TUI. Each provider page links to where to find the required credentials, validates the connection live, and writes the resulting `[provider]` block to `~/.config/cliamp/config.toml` without disturbing the rest of the file.
+Configure remote providers (Navidrome, Plex, Jellyfin, Emby, Spotify, YouTube Music) through a small TUI. Each provider page links to where to find the required credentials, validates the connection live, and writes the resulting `[provider]` block to `~/.config/cliamp/config.toml` without disturbing the rest of the file.
 
 ```sh
 cliamp setup

docs/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-For remote providers (Navidrome, Plex, Jellyfin, Spotify, YouTube Music), the fastest path is the interactive wizard:
+For remote providers (Navidrome, Plex, Jellyfin, Emby, Spotify, YouTube Music), the fastest path is the interactive wizard:
 
 ```sh
 cliamp setup
@@ -77,6 +77,10 @@ token = "$PLEX_TOKEN"
 url = "https://jelly.example.com"
 token = "${JELLYFIN_TOKEN}"
 
+[emby]
+url = "https://emby.example.com"
+token = "${EMBY_TOKEN}"
+
 [ytmusic]
 client_id = "${YTMUSIC_CLIENT_ID}"
 client_secret = "${YTMUSIC_CLIENT_SECRET}"
@@ -97,7 +101,7 @@ Set which provider to start with:
 provider = "radio"
 ```
 
-Valid values: `radio` (default), `navidrome`, `spotify`, `plex`, `jellyfin`, `soundcloud`, `yt`, `youtube`, `ytmusic`.
+Valid values: `radio` (default), `navidrome`, `spotify`, `plex`, `jellyfin`, `emby`, `soundcloud`, `yt`, `youtube`, `ytmusic`.
 
 You can also override from the CLI: `cliamp --provider jellyfin`.
 

docs/emby.md

@@ -0,0 +1,67 @@
+# Emby
+
+cliamp can stream music directly from an Emby server using Emby's authenticated HTTP API. The integration exposes your music libraries as a flat album list in the normal provider pane, following the same shape as the Jellyfin and Plex providers.
+
+> **Quick start:** run `cliamp setup` for a guided TUI that lets you pick API-key or username+password auth, validates against `/System/Info`, and writes the `[emby]` block for you. Manual setup steps are below.
+
+## Prerequisites
+
+- A reachable Emby server
+- At least one library with `CollectionType = music`
+- An Emby API key or user credentials
+
+## Configuration
+
+Add an `[emby]` section to `~/.config/cliamp/config.toml`:
+
+```toml
+[emby]
+url = "https://emby.example.com"
+user = "alice"
+password = "your_password_here"
+# optional alternatives:
+# token = "xxxxxxxxxxxxxxxxxxxx"
+# user_id = "00000000000000000000000000000000"
+```
+
+| Key | Description |
+|-----|-------------|
+| `url` | Base URL of your Emby server |
+| `user` | Emby username — used for password login, and to select the matching account when using an API key |
+| `password` | Emby password for password-based login |
+| `token` | Emby API key — alternative to username/password |
+| `user_id` | Optional Emby user id to skip discovery |
+
+## Usage
+
+Once configured, **Emby** appears as a provider alongside Radio, Navidrome, Plex, Jellyfin, Spotify, and the YouTube providers.
+
+To start cliamp with Emby selected:
+
+```bash
+cliamp --provider emby
+```
+
+Or set it in config:
+
+```toml
+provider = "emby"
+```
+
+The provider exposes a flat list of albums:
+
+```text
+Artist — Album Title (Year)
+```
+
+Select an album to load its tracks, then play as normal. Press `E` anywhere in the UI to switch to Emby quickly.
+
+## How it works
+
+cliamp authenticates with either a configured API key or the supplied username/password, resolves the active Emby user, enumerates music library views, fetches album items from those views, then fetches track items for the selected album. Playback uses Emby's authenticated download endpoint, so the existing cliamp HTTP pipeline can stream the result directly.
+
+## Known limitations
+
+- **Album list is flat**: no artist drill-down yet
+- **Token-based access**: store the API key carefully
+- **API key user selection**: Emby API keys are server-level (no "current user"). When no `user` is configured, cliamp picks the first user returned by `/Users`. On single-user servers this is always correct; on multi-user servers, set `user_id` explicitly in `[emby]` to target a specific account.

docs/keybindings.md

@@ -49,7 +49,7 @@ Press `Ctrl+K` in the player to see all keybindings.
 | Key | Action |
 |---|---|
 | `f` | Toggle bookmark ★ on selected track (or favorite radio station in radio browser) |
-| `Ctrl+F` | Search — active provider's native search (Spotify, Navidrome, Jellyfin, Plex, Local) or YouTube fallback. Available from playlist and provider-browser views. |
+| `Ctrl+F` | Search — active provider's native search (Spotify, Navidrome, Jellyfin, Emby, Plex, Local) or YouTube fallback. Available from playlist and provider-browser views. |
 | `u` | Load URL (stream/playlist) |
 | `y` | Show lyrics |
 | `Ctrl+S` | Save track to ~/Music |
@@ -59,6 +59,7 @@ Press `Ctrl+K` in the player to see all keybindings.
 | `S` | Open Spotify provider |
 | `P` | Open Plex provider |
 | `J` | Open Jellyfin provider |
+| `E` | Open Emby provider |
 | `Y` | Open YouTube provider |
 | `C` | Open SoundCloud provider |
 
@@ -87,7 +88,7 @@ Press `Ctrl+K` in the player to see all keybindings.
 
 ## Provider browser (`N` key)
 
-When you press `N` to drill into a provider (Navidrome, Plex, Jellyfin, Spotify, YouTube Music), the album/artist/track screens use:
+When you press `N` to drill into a provider (Navidrome, Plex, Jellyfin, Emby, Spotify, YouTube Music), the album/artist/track screens use:
 
 | Key | Action |
 |---|---|
@@ -99,7 +100,7 @@ When you press `N` to drill into a provider (Navidrome, Plex, Jellyfin, Spotify,
 | `a` | Append all visible tracks to the queue |
 | `q` | Queue the highlighted track to play next |
 | `s` | Cycle album sort (album list only) |
-| `S` `N` `P` `J` `Y` `L` `R` | Quick-switch to that provider without going back through the main pane |
+| `S` `N` `P` `J` `E` `Y` `L` `R` | Quick-switch to that provider without going back through the main pane |
 | `Esc` `b` | Walk back one level / close the browser |
 
 The track screen shows a `N tracks · 47:22` subtitle and right-aligned per-track durations when the provider returns them.
@@ -115,7 +116,7 @@ The playlists pane (visible when focus is on a provider — Spotify, Navidrome,
 | `/` | Filter the playlist list |
 | `Ctrl+F` | Online/server search (Spotify/Navidrome/etc.'s own search) |
 | `Ctrl+R` | Refresh — re-pull the playlist list from the provider |
-| `S` `N` `P` `J` `Y` `L` `R` | Switch to that provider |
+| `S` `N` `P` `J` `E` `Y` `L` `R` | Switch to that provider |
 | `Tab` | Switch focus to EQ |
 | `Esc` `b` | Back to the playlist pane |