From f0518edf4443890f8a26f98cddc980462d2f74d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bjarne=20=C3=98verli?= Date: Thu, 2 Apr 2026 15:56:49 +0200 Subject: [PATCH] Update docs --- docs/cli.md | 2 +- docs/jellyfin.md | 8 ++++---- docs/lyrics.md | 4 ++-- docs/navidrome.md | 6 +++--- docs/playlists.md | 18 +++++++++--------- docs/plex.md | 16 ++++++++-------- docs/plugins.md | 2 +- docs/provider-development.md | 18 +++++++++--------- docs/spotify.md | 14 +++++++------- docs/ssh-streaming.md | 4 ++-- docs/themes.md | 2 +- docs/youtube-music.md | 22 +++++++++++----------- site/index.html | 34 +++++++++++++++++----------------- ui/model/view_state_test.go | 2 +- 14 files changed, 76 insertions(+), 76 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 3292376..7266f52 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -50,7 +50,7 @@ Press `f` in the player to search YouTube interactively, or `F` (Shift+F) to sea ## Mixing flags and files -Flags can appear anywhere — before, after, or between positional arguments: +Flags can appear before, after, or between positional arguments: ```sh cliamp --shuffle track.mp3 --volume -5 diff --git a/docs/jellyfin.md b/docs/jellyfin.md index abc65ce..b9b6d2d 100644 --- a/docs/jellyfin.md +++ b/docs/jellyfin.md @@ -49,7 +49,7 @@ provider = "jellyfin" The provider currently exposes a flat list of albums: ```text -Artist — Album Title (Year) +Artist - Album Title (Year) ``` Select an album to load its tracks, then play as normal. @@ -60,6 +60,6 @@ cliamp authenticates with either a configured token or the supplied username/pas ## Known limitations -- **Album list is flat** — no artist drill-down yet -- **No scrobbling/write-back** — plays are not reported back to Jellyfin yet -- **Token-based access** — store the API token carefully +- **Album list is flat**: no artist drill-down yet +- **No scrobbling/write-back**: plays are not reported back to Jellyfin yet +- **Token-based access**: store the API token carefully diff --git a/docs/lyrics.md b/docs/lyrics.md index 432ee4a..7d87c3c 100644 --- a/docs/lyrics.md +++ b/docs/lyrics.md @@ -4,8 +4,8 @@ Press `y` to show lyrics for the current track. Lyrics are fetched from LRCLIB a ## Modes -- **Synced lyrics** — for local files and Navidrome tracks, lyrics auto scroll and highlight the active line in time with playback. -- **Scroll mode** — for streams and plain lyrics without timestamps, use `j`/`k` or arrow keys to scroll manually. +- **Synced lyrics**: for local files and Navidrome tracks, lyrics auto scroll and highlight the active line in time with playback. +- **Scroll mode**: for streams and plain lyrics without timestamps, use `j`/`k` or arrow keys to scroll manually. ## Streams diff --git a/docs/navidrome.md b/docs/navidrome.md index 0db6b86..045ce53 100644 --- a/docs/navidrome.md +++ b/docs/navidrome.md @@ -47,9 +47,9 @@ After loading a playlist you return to the standard playlist view with all the u Press `N` at any time (or from the provider panel) to open the full-screen Navidrome browser. It lets you explore your library in three modes: -- **By Album** — browse a paginated list of all albums, then open any album to see its tracks. -- **By Artist** — browse all artists; selecting one loads every track across all their albums, grouped by album with separator headers. -- **By Artist / Album** — three-level drill-down: artist → album list → track list. +- **By Album**: browse a paginated list of all albums, then open any album to see its tracks. +- **By Artist**: browse all artists; selecting one loads every track across all their albums, grouped by album with separator headers. +- **By Artist / Album**: three-level drill-down: artist → album list → track list. ### Browser controls diff --git a/docs/playlists.md b/docs/playlists.md index 765a8c0..acde165 100644 --- a/docs/playlists.md +++ b/docs/playlists.md @@ -24,7 +24,7 @@ http://station-1.com/stream http://station-2.com/stream/hd ``` -Entries without `#EXTINF` still work — the filename or URL is used as the title instead. +Entries without `#EXTINF` still work. The filename or URL is used as the title instead. ### Relative Paths @@ -87,7 +87,7 @@ HTTP/HTTPS paths are automatically treated as streams. ### Podcast / RSS Feed Playlists -You can save podcast RSS feed URLs in a playlist. Add `feed = true` to mark a track as a feed — when played, the feed is resolved into individual episodes instead of being streamed directly. +You can save podcast RSS feed URLs in a playlist. Add `feed = true` to mark a track as a feed. When played, the feed is resolved into individual episodes instead of being streamed directly. ```toml # ~/.config/cliamp/playlists/podcasts.toml @@ -133,13 +133,13 @@ cliamp song.mp3 # starts playing, Esc opens browser Press `p` from any view to open the playlist manager: -1. **Browse** — see all playlists with track counts -2. **Open** — press `Enter` or `→` to view tracks inside a playlist -3. **Add track** — press `a` to add the currently playing track -4. **Delete playlist** — press `d` then `y` to confirm deletion -5. **Remove track** — open a playlist, highlight a track, press `d` to remove it -6. **Play all** — press `Enter` on the track list to load all tracks into the player -7. **New playlist** — select "+ New Playlist...", type a name, and press Enter +1. **Browse**: see all playlists with track counts +2. **Open**: press `Enter` or `→` to view tracks inside a playlist +3. **Add track**: press `a` to add the currently playing track +4. **Delete playlist**: press `d` then `y` to confirm deletion +5. **Remove track**: open a playlist, highlight a track, press `d` to remove it +6. **Play all**: press `Enter` on the track list to load all tracks into the player +7. **New playlist**: select "+ New Playlist...", type a name, and press Enter The directory `~/.config/cliamp/playlists/` is created automatically on first use. Removing the last track from a playlist auto-deletes the file. diff --git a/docs/plex.md b/docs/plex.md index a80f813..de9dc0f 100644 --- a/docs/plex.md +++ b/docs/plex.md @@ -1,6 +1,6 @@ # Plex Media Server -cliamp can stream music directly from your Plex Media Server, giving you access to your full Plex music library — including any library served by PlexAmp. Streaming uses the same Plex HTTP API that official Plex clients use; no extra software is required. +cliamp can stream music directly from your Plex Media Server, giving you access to your full Plex music library, including any library served by PlexAmp. Streaming uses the same Plex HTTP API that official Plex clients use; no extra software is required. ## Prerequisites @@ -41,7 +41,7 @@ Once configured, **Plex** appears as a provider in the cliamp TUI alongside Radi The provider exposes your music library as a flat list of albums, labelled: ``` -Artist — Album Title (Year) +Artist - Album Title (Year) ``` Select an album to load its tracks, then play as normal. @@ -66,12 +66,12 @@ cliamp calls the Plex HTTP API to enumerate your music libraries and albums. Whe http://:32400/library/parts///file.?X-Plex-Token= ``` -These are direct file-serve URLs — Plex serves the original file without transcoding, and cliamp's existing HTTP streaming pipeline handles playback. All formats supported by cliamp (MP3, FLAC, AAC, OGG, OPUS, WAV, etc.) work as long as the original file format is one of them. +These are direct file-serve URLs. Plex serves the original file without transcoding, and cliamp's existing HTTP streaming pipeline handles playback. All formats supported by cliamp (MP3, FLAC, AAC, OGG, OPUS, WAV, etc.) work as long as the original file format is one of them. ## Known limitations -- **No scrobbling** — play counts are not reported back to Plex -- **No playlist write-back** — cliamp cannot create or modify Plex playlists -- **Token is long-lived** — store it carefully; it grants full access to your Plex account -- **Album list is flat** — no artist drill-down; search by scrolling or using cliamp's search -- **No Plex playlists** — only library albums are exposed (Plex user-created playlists are not yet surfaced) +- **No scrobbling**: play counts are not reported back to Plex +- **No playlist write-back**: cliamp cannot create or modify Plex playlists +- **Token is long-lived**: store it carefully; it grants full access to your Plex account +- **Album list is flat**: no artist drill-down; search by scrolling or using cliamp's search +- **No Plex playlists**: only library albums are exposed (Plex user-created playlists are not yet surfaced) diff --git a/docs/plugins.md b/docs/plugins.md index 33591fb..ac1e5ec 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -1,6 +1,6 @@ # Lua Plugins -cliamp has a Lua 5.1 plugin system. Plugins can hook into playback events (scrobbling, notifications, status bar output) and add custom visualizers. Each plugin runs in an isolated VM — a crash in one plugin cannot affect others or the player. +cliamp has a Lua 5.1 plugin system. Plugins can hook into playback events (scrobbling, notifications, status bar output) and add custom visualizers. Each plugin runs in an isolated VM. A crash in one plugin cannot affect others or the player. Plugins live in `~/.config/cliamp/plugins/`. Create the directory: diff --git a/docs/provider-development.md b/docs/provider-development.md index 7449eb5..2bd9a87 100644 --- a/docs/provider-development.md +++ b/docs/provider-development.md @@ -7,11 +7,11 @@ discovers capabilities at runtime via type assertions and enables features accordingly. See the existing providers for reference: -- `external/navidrome/` — Subsonic API, browsing, scrobbling -- `external/plex/` — Plex Media Server, search, album tracks -- `external/spotify/` — Spotify, search, playlist management, custom streaming -- `external/radio/` — internet radio, favorites -- `external/local/` — local TOML playlist files +- `external/navidrome/`: Subsonic API, browsing, scrobbling +- `external/plex/`: Plex Media Server, search, album tracks +- `external/spotify/`: Spotify, search, playlist management, custom streaming +- `external/radio/`: internet radio, favorites +- `external/local/`: local TOML playlist files ## Base Interface (required) @@ -105,11 +105,11 @@ func (p *Provider) AlbumTracks(albumID string) ([]playlist.Track, error) { When building `playlist.Track` values: -- **`Path`** — the playable URL or file path. For HTTP streams, use a full URL. +- **`Path`**: the playable URL or file path. For HTTP streams, use a full URL. For custom URI schemes (e.g. `spotify:track:xxx`), implement `CustomStreamer`. -- **`Stream: true`** — set this for HTTP URLs so the player uses the streaming +- **`Stream: true`**: set this for HTTP URLs so the player uses the streaming pipeline. -- **`ProviderMeta`** — attach provider-specific metadata as a string map with +- **`ProviderMeta`**: attach provider-specific metadata as a string map with namespaced keys. This is used for features like scrobbling: ```go @@ -190,4 +190,4 @@ implements, the UI will automatically: - Call `Close()` on shutdown if `Closer` is implemented The "N" and "F" shortcuts work regardless of which provider is currently active -— they find the first registered provider with the needed capability. +They find the first registered provider with the needed capability. diff --git a/docs/spotify.md b/docs/spotify.md index dc44848..cea6cb2 100644 --- a/docs/spotify.md +++ b/docs/spotify.md @@ -1,6 +1,6 @@ # Spotify Integration -Cliamp can stream your [Spotify](https://www.spotify.com/) library directly through its audio pipeline — EQ, visualizer, and all effects apply. Requires a [Spotify Premium](https://www.spotify.com/premium/) account. +Cliamp can stream your [Spotify](https://www.spotify.com/) library directly through its audio pipeline. EQ, visualizer, and all effects apply. Requires a [Spotify Premium](https://www.spotify.com/premium/) account. ## Setup @@ -23,7 +23,7 @@ Add your client ID to `~/.config/cliamp/config.toml`: client_id = "your_client_id_here" ``` -Run `cliamp`, select Spotify as a provider, and press Enter to sign in. Credentials are cached at `~/.config/cliamp/spotify_credentials.json` — subsequent launches refresh silently. +Run `cliamp`, select Spotify as a provider, and press Enter to sign in. Credentials are cached at `~/.config/cliamp/spotify_credentials.json`. Subsequent launches refresh silently. ## Usage @@ -46,14 +46,14 @@ After loading a playlist you return to the standard playlist view with all the u ## Playlists -Only playlists in your Spotify library are shown — this includes playlists you've created and playlists you've saved (followed). If a public playlist doesn't appear, open Spotify and click **Save** on it first. There's no need to copy tracks to a new playlist. +Only playlists in your Spotify library are shown. This includes playlists you've created and playlists you've saved (followed). If a public playlist doesn't appear, open Spotify and click **Save** on it first. There's no need to copy tracks to a new playlist. ## Troubleshooting -- **"OAuth failed"** — Make sure your redirect URI is exactly `http://127.0.0.1:19872/login` in the Spotify dashboard (no trailing slash). -- **Playlist not showing** — You must save/follow the playlist in Spotify for it to appear. Only your library playlists are listed. -- **Playback issues** — Spotify integration requires a Premium account. Free accounts cannot stream. -- **Re-authenticate** — Delete `~/.config/cliamp/spotify_credentials.json` and restart cliamp to trigger a fresh login. +- **"OAuth failed"**: Make sure your redirect URI is exactly `http://127.0.0.1:19872/login` in the Spotify dashboard (no trailing slash). +- **Playlist not showing**: You must save/follow the playlist in Spotify for it to appear. Only your library playlists are listed. +- **Playback issues**: Spotify integration requires a Premium account. Free accounts cannot stream. +- **Re-authenticate**: Delete `~/.config/cliamp/spotify_credentials.json` and restart cliamp to trigger a fresh login. ## Requirements diff --git a/docs/ssh-streaming.md b/docs/ssh-streaming.md index 033094a..fa08e66 100644 --- a/docs/ssh-streaming.md +++ b/docs/ssh-streaming.md @@ -70,9 +70,9 @@ Formats requiring ffmpeg (`.m4a`, `.wma`) may not work over SSH since the ffmpeg | Scenario | Behavior | |----------|----------| | Host unreachable | Player shows error, advances to next track | -| Auth failure | SSH uses `BatchMode=yes` — never hangs on password prompts | +| Auth failure | SSH uses `BatchMode=yes` and never hangs on password prompts | | Connection drops mid-stream | Player detects EOF, advances to next track | -| Unknown host key | Rejected — add the host to `~/.ssh/known_hosts` first, or configure in `~/.ssh/config` | +| Unknown host key | Rejected. Add the host to `~/.ssh/known_hosts` first, or configure in `~/.ssh/config` | ## Mixing Local and SSH Tracks diff --git a/docs/themes.md b/docs/themes.md index d395bed..2e82f2c 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -1,6 +1,6 @@ # Themes -cliamp ships with 20 built-in color themes and supports custom themes via simple TOML files. +cliamp ships with 17 built-in color themes and supports custom themes via simple TOML files. Press `t` during playback to open the theme picker. Navigate with `↑`/`↓`, preview live as you move, confirm with `Enter`, or cancel with `Esc`. diff --git a/docs/youtube-music.md b/docs/youtube-music.md index 6beb63b..7ce30fd 100644 --- a/docs/youtube-music.md +++ b/docs/youtube-music.md @@ -1,10 +1,10 @@ # YouTube & YouTube Music Integration -Cliamp can browse your [YouTube](https://youtube.com/) and [YouTube Music](https://music.youtube.com/) playlists and play tracks through its audio pipeline — EQ, visualizer, and all effects apply. Playback uses yt-dlp, which must be installed. +Cliamp can browse your [YouTube](https://youtube.com/) and [YouTube Music](https://music.youtube.com/) playlists and play tracks through its audio pipeline. EQ, visualizer, and all effects apply. Playback uses yt-dlp, which must be installed. Your playlists are automatically classified into two providers: -- **YouTube Music** — playlists containing music content -- **YouTube** — playlists containing non-music content (podcasts, vlogs, tutorials, etc.) +- **YouTube Music**: playlists containing music content +- **YouTube**: playlists containing non-music content (podcasts, vlogs, tutorials, etc.) ## Setup @@ -47,7 +47,7 @@ cookies_from = "chrome" Supported browsers: `chrome`, `firefox`, `brave`, `edge`, `opera`, `safari`, `chromium`. -Run `cliamp` (or `cliamp --provider ytmusic` / `cliamp --provider youtube`), select a provider, and press Enter to sign in. Credentials are cached at `~/.config/cliamp/ytmusic_credentials.json` — subsequent launches refresh silently. +Run `cliamp` (or `cliamp --provider ytmusic` / `cliamp --provider youtube`), select a provider, and press Enter to sign in. Credentials are cached at `~/.config/cliamp/ytmusic_credentials.json`. Subsequent launches refresh silently. ## Usage @@ -79,21 +79,21 @@ Playlists are automatically split between the two providers: - Playlists containing music content (auto-classified by video category) **YouTube** shows: -- **Liked Videos** — your liked videos (YouTube's special `LL` playlist) +- **Liked Videos**: your liked videos (YouTube's special `LL` playlist) - Playlists containing non-music content Classification is determined by sampling a video from each playlist and checking its YouTube category. Results are cached at `~/.config/cliamp/ytmusic_classification.json`. Delete this file to reclassify. ## Troubleshooting -- **"OAuth failed"** — Make sure your Google Cloud project has YouTube Data API v3 enabled and your OAuth client type is "Desktop app". -- **"Access blocked"** — While your app is in "Testing" status, only test users you've added can sign in. Add your Google account as a test user in the OAuth consent screen settings. -- **Playlist not showing** — Only playlists in your library are listed. Save/follow a playlist in YouTube Music for it to appear. -- **Re-authenticate** — Delete `~/.config/cliamp/ytmusic_credentials.json` and restart cliamp to trigger a fresh login. -- **Private/deleted videos** — These are automatically skipped when loading a playlist. +- **"OAuth failed"**: Make sure your Google Cloud project has YouTube Data API v3 enabled and your OAuth client type is "Desktop app". +- **"Access blocked"**: While your app is in "Testing" status, only test users you've added can sign in. Add your Google account as a test user in the OAuth consent screen settings. +- **Playlist not showing**: Only playlists in your library are listed. Save/follow a playlist in YouTube Music for it to appear. +- **Re-authenticate**: Delete `~/.config/cliamp/ytmusic_credentials.json` and restart cliamp to trigger a fresh login. +- **Private/deleted videos**: These are automatically skipped when loading a playlist. ## Requirements - [yt-dlp](https://github.com/yt-dlp/yt-dlp) installed and on your PATH (for audio playback) - A Google Cloud project with YouTube Data API v3 enabled -- No Spotify Premium or other paid subscription required — YouTube Music free tier works +- No Spotify Premium or other paid subscription required. YouTube Music free tier works diff --git a/site/index.html b/site/index.html index 3852d55..eb981d7 100644 --- a/site/index.html +++ b/site/index.html @@ -3,7 +3,7 @@ -CLIAMP — Terminal Music Player +CLIAMP - Terminal Music Player