chore: import upstream snapshot with attribution

2026-07-13 12:31:13 +08:00
commit ead81af521
414 changed files with 73946 additions and 0 deletions
@@ -0,0 +1,201 @@
+# CLI Flags
+
+Override any config option for a single session without editing `~/.config/cliamp/config.toml`. Flags can appear before or after file/URL arguments.
+
+## Playback
+
+```sh
+cliamp --volume -5 track.mp3          # volume in dB [-30, +6]
+cliamp --shuffle ~/Music              # enable shuffle
+cliamp --repeat all ~/Music           # repeat mode: off, all, one
+cliamp --mono track.mp3               # downmix to mono
+cliamp --no-mono track.mp3            # force stereo
+cliamp --auto-play ~/Music            # start playback immediately
+cliamp --playlist "Blade Runner"      # load a local TOML playlist (add --auto-play to start playback)
+```
+
+## Audio engine
+
+```sh
+cliamp --sample-rate 48000 track.mp3      # output sample rate (22050, 44100, 48000, 96000, 192000)
+cliamp --buffer-ms 200 track.mp3          # speaker buffer in ms (50–500)
+cliamp --resample-quality 1 track.mp3     # resample quality factor (1–4)
+cliamp --bit-depth 32 track.m4a           # PCM bit depth: 16 (default) or 32 (lossless)
+```
+
+## Appearance
+
+```sh
+cliamp --compact ~/Music                     # cap width at 80 columns
+cliamp --eq-preset "Bass Boost" ~/Music
+```
+
+## Diagnostics
+
+```sh
+cliamp --log-level debug                     # raise log verbosity for one session
+```
+
+Logs are written to `~/.config/cliamp/cliamp.log`. Levels: `debug`, `info` (default), `warn`, `error`.
+
+## Low-power mode
+
+```sh
+cliamp --low-power track.mp3                 # reduce CPU load for this session
+```
+
+Reduces CPU load by lowering UI/render cadence and forcing the visualizer to `none`. Useful on battery, slow terminals, or SSH sessions. Press `v` in the player to cycle visualizers back on at any time.
+
+To make this persistent, set it in `~/.config/cliamp/config.toml`:
+
+```toml
+low_power = true
+```
+
+## Headless daemon mode
+
+```sh
+cliamp --daemon                              # no TUI, IPC only
+cliamp --daemon --auto-play --playlist Lofi  # start playing on launch
+cliamp -d ~/Music --auto-play                # short flag form
+```
+
+Runs cliamp without rendering a UI, listening on the same Unix socket the TUI uses. All `cliamp <subcommand>` IPC clients keep working. UI-specific commands (`theme`, `vis`) return an error in this mode. See [Headless Daemon Mode](headless.md) for use cases and example configs (Waybar, Hyprland, systemd, cron).
+
+## Search
+
+Search and play a track directly from the command line (requires [yt-dlp](https://github.com/yt-dlp/yt-dlp)):
+
+```sh
+cliamp search "never gonna give you up"       # search YouTube
+cliamp search-sc "lofi beats"                  # search SoundCloud
+```
+
+Press `Ctrl+F` in the player for context-aware search: it runs the active provider's native search when available or falls back to YouTube search.
+
+## General
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--help` | `-h` | Show help and exit |
+| `--version` | `-v` | Print version and exit |
+| `--upgrade` | | Update to the latest release |
+
+## Mixing flags and files
+
+Flags can appear before, after, or between positional arguments:
+
+```sh
+cliamp --shuffle track.mp3 --volume -5
+cliamp track.mp3 --repeat all --mono ~/Music
+```
+
+## Flag reference
+
+| Flag | Type | Default | Range / Values |
+|------|------|---------|----------------|
+| `--volume` | float | 0 | -30 to +6 dB |
+| `--shuffle` | bool | false | |
+| `--repeat` | string | off | off, all, one |
+| `--mono` / `--no-mono` | bool | false | |
+| `--auto-play` | bool | false | |
+| `--compact` | bool | false | |
+| `--theme` | string | | theme name |
+| `--eq-preset` | string | | preset name |
+| `--sample-rate` | int | 44100 | 22050, 44100, 48000, 96000, 192000 |
+| `--buffer-ms` | int | 100 | 50–500 |
+| `--resample-quality` | int | 4 | 1–4 |
+| `--bit-depth` | int | 16 | 16, 32 |
+| `--playlist` | string | | local TOML playlist name |
+| `--log-level` | string | info | debug, info, warn, error |
+| `--low-power` | bool | false | lowers UI cadence; disables visualization |
+| `--daemon` / `-d` | bool | false | run headless; IPC only, no TUI |
+
+CLI flags override config file values for the current session only. They are not persisted.
+
+## Setup wizard
+
+Configure remote providers (Navidrome, Plex, Jellyfin, Emby, Spotify, Qobuz, NetEase, 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
+```
+
+Keys: `↑/↓` to navigate, `Enter` to confirm or submit, `Esc` to back out, `q` from the menu to quit. Passwords and tokens are masked. Running setup again for an already-configured provider replaces its section in place.
+
+## Playlist Management
+
+Manage local TOML playlists from the command line without opening the TUI.
+
+```sh
+cliamp playlist list                          # list playlists with track counts
+cliamp playlist create "Name"                 # create an empty playlist
+cliamp playlist create "Name" file1 dir/ ...  # create from files/folders (recursive, skips duplicate paths)
+cliamp playlist create "Name" --ssh HOST dir/ # create from remote machine via SSH
+cliamp playlist add "Name" file1 ...          # append tracks to existing playlist, skipping duplicates
+cliamp playlist rename "Old" "New"            # rename a playlist
+cliamp playlist show "Name"                   # display tracks
+cliamp playlist show "Name" --json            # machine-readable output
+cliamp playlist remove "Name" --index 3       # remove track by index
+cliamp playlist dedupe "Name"                 # remove duplicate paths, keeping the first
+cliamp playlist sort "Name" --by album         # sort in place
+cliamp playlist doctor [Name]                  # report missing local files
+cliamp playlist doctor "Name" --fix            # prune missing local files
+cliamp playlist export "Name" -o mix.m3u       # export as M3U
+cliamp playlist export "Name" --format pls     # export as PLS to stdout
+cliamp playlist import mix.m3u --name "Name"   # import local M3U/M3U8/PLS
+cliamp playlist bookmark "Name" --index 3      # toggle bookmark flag
+cliamp playlist bookmarks                       # list bookmarked tracks
+cliamp playlist enrich "Name"                  # probe duration/album metadata
+cliamp playlist delete "Name"                 # delete entire playlist
+```
+
+Sort keys: `track`, `title`, `artist`, `album`, `artist+album`, `path`.
+
+See [playlists.md](playlists.md) for the TOML format and [ssh-streaming.md](ssh-streaming.md) for remote playback.
+
+## Recently Played
+
+```sh
+cliamp history                                # show the 50 most recent plays
+cliamp history --limit 200                    # change the cap
+cliamp history --json                         # machine-readable output
+cliamp history clear                          # wipe ~/.config/cliamp/history.toml
+```
+
+A play is recorded once you've listened to a track for at least 50% of its
+duration. Inside the TUI, the same data appears as the virtual "Recently
+Played" entry in the Local Playlists provider. See [history.md](history.md).
+
+## Spotify
+
+```sh
+cliamp spotify reset                          # clear stored Spotify credentials
+```
+
+Use `spotify reset` if you see persistent `rate-limited on /v1/me` warnings or stale auth errors. After running it, relaunch cliamp and select Spotify to sign in again. See [spotify.md](spotify.md) for the full setup guide.
+
+## Remote Control (IPC)
+
+Control a running cliamp instance from another terminal:
+
+```sh
+cliamp play / pause / toggle / stop    # playback control
+cliamp next / prev                     # track navigation
+cliamp status                          # current state
+cliamp status --json                   # machine-readable state
+cliamp volume -5                       # adjust volume (dB)
+cliamp seek 30                         # seek to position (seconds)
+cliamp load "Playlist Name"            # load a playlist
+cliamp queue /path/to/file.mp3         # queue a track
+cliamp shuffle [on|off|toggle]         # toggle or set shuffle
+cliamp repeat [off|all|one|cycle]      # set or cycle repeat mode
+cliamp mono [on|off|toggle]            # toggle or set mono output
+cliamp speed 1.5                       # set playback speed (0.25–2.0)
+cliamp eq Rock                         # set EQ preset by name
+cliamp eq --band 0 6.0                 # set EQ band 0 to +6 dB
+cliamp device list                     # list audio output devices
+cliamp device "My DAC"                 # switch audio output device
+```
+
+See [remote-control.md](remote-control.md) for the full protocol specification.