github-featured/bjarneo--cliamp
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Bjarne Øverli
2026-04-02 15:56:49 +02:00
parent b6deffe92b
commit f0518edf44
14 changed files with 76 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli.md
+1 -1
View File
@@ -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
docs/jellyfin.md
+4 -4
View File
@@ -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
docs/lyrics.md
+2 -2
View File
@@ -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
docs/navidrome.md
+3 -3
View File
@@ -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
docs/playlists.md
+9 -9
View File
@@ -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.
docs/plex.md
+8 -8
View File
@@ -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://<server>:32400/library/parts/<partID>/<timestamp>/file.<ext>?X-Plex-Token=<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)
docs/plugins.md
+1 -1
View File
@@ -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:
docs/provider-development.md
+9 -9
View File
@@ -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.
docs/spotify.md
+7 -7
View File
@@ -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
docs/ssh-streaming.md
+2 -2
View File
@@ -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
docs/themes.md
+1 -1
View File
@@ -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`.
docs/youtube-music.md
+11 -11
View File
@@ -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
site/index.html
+17 -17
View File
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>CLIAMP — Terminal Music Player</title>
<title>CLIAMP - Terminal Music Player</title>
<meta name="description" content="A retro terminal music player inspired by Winamp 2.x. Play local files, YouTube, Spotify, Plex, Jellyfin, Navidrome, SoundCloud, and 30,000+ radio stations with a spectrum visualizer and 10-band EQ.">
<style>
/* ═══ RESET ═══════════════════════════════ */
@@ -802,7 +802,7 @@
<span class="terminal-dot"></span>
<span class="terminal-dot"></span>
<span class="terminal-dot"></span>
<span class="terminal-title">cliamp &mdash; bash</span>
<span class="terminal-title">cliamp - bash</span>
</div>
<!-- ═══ NAV ═══ -->
@@ -827,7 +827,7 @@
<div class="hero-title">CLIAMP<span class="hero-cursor"></span></div>
<div class="hero-sub">terminal music player</div>
<div class="hero-desc">
A retro music player inspired by <em>Winamp</em> &mdash; built for the terminal.<br>
A retro music player inspired by <em>Winamp</em>, built for the terminal.<br>
Spectrum visualizer, 10-band EQ, playlists, streaming, and more.
</div>
<div class="visualizer">
@@ -978,7 +978,7 @@
<div class="feature">
<div class="feature-icon">&#9836;</div>
<div class="feature-name">MPRIS / Media Keys</div>
<p>Linux desktop integration &mdash; control playback with hardware media keys and playerctl</p>
<p>Linux desktop integration. Control playback with hardware media keys and playerctl</p>
</div>
<div class="feature">
<div class="feature-icon">&#9881;</div>
@@ -988,12 +988,12 @@
<div class="feature">
<div class="feature-icon">&#9000;</div>
<div class="feature-name">Live Radio Metadata</div>
<p>ICY/Shoutcast metadata &mdash; see the current song title on internet radio streams</p>
<p>ICY/Shoutcast metadata. See the current song title on internet radio streams</p>
</div>
<div class="feature">
<div class="feature-icon">&#9998;</div>
<div class="feature-name">Embedded Tag Reading</div>
<p>ID3v2, Vorbis comments, and MP4 atoms &mdash; reads artist, album, genre, year, and track number</p>
<p>ID3v2, Vorbis comments, and MP4 atoms. Reads artist, album, genre, year, and track number</p>
</div>
<div class="feature">
<div class="feature-icon">&#9654;</div>
@@ -1008,7 +1008,7 @@
<div class="feature">
<div class="feature-icon">&#9835;</div>
<div class="feature-name">Spotify</div>
<p>Stream your Spotify Premium library &mdash; playlists, EQ, visualizer, and all effects apply. OAuth login with cached credentials</p>
<p>Stream your Spotify Premium library. Playlists, EQ, visualizer, and all effects apply. OAuth login with cached credentials</p>
</div>
<div class="feature">
<div class="feature-icon">&#9654;</div>
@@ -1018,7 +1018,7 @@
<div class="feature">
<div class="feature-icon">&#9654;</div>
<div class="feature-name">Plex</div>
<p>Stream music from your Plex Media Server. Browse albums and play directly &mdash; no extra software required</p>
<p>Stream music from your Plex Media Server. Browse albums and play directly. No extra software required</p>
</div>
<div class="feature">
<div class="feature-icon">&#9654;</div>
@@ -1311,7 +1311,7 @@
<div class="key-row"><kbd>F</kbd><span>Spotify search + add to playlist</span></div>
<div class="key-row"><kbd>u</kbd><span>Load URL (stream/playlist)</span></div>
<div class="key-row"><kbd>y</kbd><span>Show lyrics</span></div>
<div class="key-row"><kbd>J</kbd><span>Jump to time</span></div>
<div class="key-row"><kbd>Ctrl+J</kbd><span>Jump to time</span></div>
<div class="key-row"><kbd>x</kbd><span>Expand playlist</span></div>
<div class="key-row"><kbd>o</kbd><span>Open file browser</span></div>
<div class="key-row"><kbd>a</kbd><span>Queue (play next)</span></div>
@@ -1343,7 +1343,7 @@
<div class="section-label"><span class="label-text">plugins.lua</span></div>
<p class="plugins-intro">
Lua 5.1 plugin system. Hook into playback events, add custom visualizers, or push data to external services.
Each plugin runs in an isolated sandbox &mdash; a crash in one cannot affect others or the player.
Each plugin runs in an isolated sandbox. A crash in one cannot affect others or the player.
Drop a <code>.lua</code> file in <span class="path">~/.config/cliamp/plugins/</span> and restart.
</p>
@@ -1431,7 +1431,7 @@ p:<span class="fn">on</span>(<span class="str">"track.change"</span>, <span clas
</div>
<div class="plugin-api">
<div class="plugin-api-name">http</div>
<p>HTTP client with <code>get()</code> and <code>post()</code> &mdash; JSON, form body, custom headers. 5s timeout</p>
<p>HTTP client with <code>get()</code> and <code>post()</code>. JSON, form body, custom headers. 5s timeout</p>
</div>
<div class="plugin-api">
<div class="plugin-api-name">fs</div>
@@ -1481,15 +1481,15 @@ p:<span class="fn">on</span>(<span class="str">"track.change"</span>, <span clas
<div id="radio-error"></div>
<div class="radio-stats-row">
<div class="radio-stat">
<div class="radio-stat-value"><span class="radio-stat-dot"></span><span id="radio-now">&mdash;</span></div>
<div class="radio-stat-value"><span class="radio-stat-dot"></span><span id="radio-now">-</span></div>
<div class="radio-stat-label">listening now</div>
</div>
<div class="radio-stat">
<div class="radio-stat-value" id="radio-sessions">&mdash;</div>
<div class="radio-stat-value" id="radio-sessions">-</div>
<div class="radio-stat-label">total sessions</div>
</div>
<div class="radio-stat">
<div class="radio-stat-value" id="radio-hours">&mdash;</div>
<div class="radio-stat-value" id="radio-hours">-</div>
<div class="radio-stat-label">listen hours</div>
</div>
</div>
@@ -1699,7 +1699,7 @@ function renderStationStats(data,stationKey){
bar.style.background=barColors[stationKey]||barColors.lofi;
var tip=document.createElement("div");
tip.className="tooltip";
tip.textContent=d.date+" \u2014 "+d.sessions+" sessions \u00B7 "+d.listen_hours.toFixed(1)+"h";
tip.textContent=d.date+" - "+d.sessions+" sessions, "+d.listen_hours.toFixed(1)+"h";
bar.appendChild(tip);
chart.appendChild(bar);
});
@@ -1751,7 +1751,7 @@ function renderStationStats(data,stationKey){
tEl.appendChild(div);
});
/* globe — only init once */
/* globe - only init once */
if(!window._globeInitialized){
window._radioCountries=activeCountries;
initGlobe(activeCountries);
@@ -1801,7 +1801,7 @@ var _globeAnim=null;
var _globeResizeTimer=null;
var _landPolygons=null;
/* Minimal TopoJSON decoder — extracts rings from a topology object */
/* Minimal TopoJSON decoder - extracts rings from a topology object */
function topoToPolygons(topo,objectName){
var obj=topo.objects[objectName];
var arcs=topo.arcs;
ui/model/view_state_test.go
+1 -1
View File
@@ -92,7 +92,7 @@ func TestRenderPlaylistKeepsCursorVisibleWhenFooterShrinksBudget(t *testing.T) {
}
out := m.renderPlaylist()
if !strings.Contains(out, "10. Track 10") {
if !strings.Contains(out, "Track 10") {
t.Fatalf("renderPlaylist() = %q, want selected row to remain visible", out)
}
}