wehub-resource-sync
155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# Remote Control (IPC)
|
|
|
|
Control a running cliamp instance from another terminal, a shell script, or an AI coding assistant.
|
|
|
|
When cliamp starts, it listens on a local IPC socket at `~/.config/cliamp/cliamp.sock` (or `%APPDATA%\cliamp\cliamp.sock` on Windows when `HOME` is unset). CLI subcommands connect to this socket to send playback commands and receive status. On Windows 10/11, this uses the same local socket transport via Go's AF_UNIX support.
|
|
|
|
## Playback Commands
|
|
|
|
```sh
|
|
cliamp play # resume playback
|
|
cliamp pause # pause playback
|
|
cliamp toggle # play/pause toggle
|
|
cliamp next # next track
|
|
cliamp prev # previous track
|
|
cliamp stop # stop playback
|
|
```
|
|
|
|
## Status
|
|
|
|
```sh
|
|
cliamp status # human-readable current state
|
|
cliamp status --json # machine-readable JSON
|
|
```
|
|
|
|
JSON output:
|
|
|
|
```json
|
|
{
|
|
"ok": true,
|
|
"state": "playing",
|
|
"track": {
|
|
"title": "Imperial March",
|
|
"artist": "John Williams",
|
|
"path": "/path/to/file.mp3"
|
|
},
|
|
"position": 42.5,
|
|
"duration": 183.0,
|
|
"volume": -3,
|
|
"playlist": "Star Wars OT",
|
|
"index": 12,
|
|
"total": 59,
|
|
"visualizer": "ClassicPeak",
|
|
"theme": {
|
|
"name": "Kanagawa Dragon",
|
|
"accent": "#658594",
|
|
"fg": "#c5c9c5",
|
|
"green": "#8a9a7b",
|
|
"yellow": "#c4b28a",
|
|
"red": "#c4746e"
|
|
}
|
|
}
|
|
```
|
|
|
|
The `theme` block carries the active cliamp theme's resolved hex colors. Empty hex fields mean the default ANSI fallback theme is active.
|
|
|
|
## Volume and Seek
|
|
|
|
```sh
|
|
cliamp volume -5 # adjust volume in dB
|
|
cliamp seek 30 # seek to position in seconds
|
|
```
|
|
|
|
## Playlist Loading
|
|
|
|
```sh
|
|
cliamp load "Playlist Name" # load a playlist into the player
|
|
cliamp queue /path/to.mp3 # queue a single track
|
|
```
|
|
|
|
## Spectrum Streaming
|
|
|
|
```sh
|
|
cliamp visstream # NDJSON spectrum frames at 30 fps (default)
|
|
cliamp visstream --fps 60 # up to 60 fps; clamped to [1, 60]
|
|
```
|
|
|
|
`visstream` holds a single IPC connection open and emits one JSON line per frame containing the 10-band spectrum and the active visualizer mode name:
|
|
|
|
```json
|
|
{"ok":true,"visualizer":"Bars","bands":[0.93,0.81,0.62,0.48,0.31,0.22,0.14,0.09,0.04,0.01]}
|
|
```
|
|
|
|
Band values are normalized to [0, 1], in the same shape cliamp uses internally for spectrum visualizers. This is what powers the [Quickshell now-playing widget](quickshell.md). Consumers can pipe stdout directly into another process (`cliamp visstream | jq`) or use it from a long-lived subprocess in a UI toolkit.
|
|
|
|
Under the hood it issues a `{"cmd":"bands"}` request per tick over the existing IPC socket; you can also issue this command directly from your own client if you want frame-pulled access:
|
|
|
|
```json
|
|
{"cmd": "bands"}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"ok": true, "visualizer": "Bars", "bands": [0.93, 0.81, ...]}
|
|
```
|
|
|
|
## Protocol
|
|
|
|
The IPC protocol is newline-delimited JSON over a local stream socket. Each request is a single JSON object followed by a newline. The server responds with a single JSON object followed by a newline.
|
|
|
|
Request format:
|
|
|
|
```json
|
|
{"cmd": "status"}
|
|
{"cmd": "next"}
|
|
{"cmd": "volume", "value": -5}
|
|
{"cmd": "load", "playlist": "Star Wars OT"}
|
|
{"cmd": "queue", "path": "/path/to/file.mp3"}
|
|
```
|
|
|
|
Response format:
|
|
|
|
```json
|
|
{"ok": true}
|
|
{"ok": true, "state": "playing", "track": {...}, ...}
|
|
{"ok": false, "error": "cliamp is not running"}
|
|
```
|
|
|
|
## Socket Details
|
|
|
|
- **Path**: `~/.config/cliamp/cliamp.sock` (or `%APPDATA%\cliamp\cliamp.sock` on Windows when `HOME` is unset; created on TUI start, removed on shutdown)
|
|
- **Permissions**: `0600` (owner only)
|
|
- **Stale detection**: A PID file (`cliamp.sock.pid`) tracks the owning process. If cliamp crashes, the next instance detects the stale socket and cleans it up.
|
|
|
|
## Scripting Examples
|
|
|
|
```sh
|
|
# Skip to next track and show what's playing
|
|
cliamp next && cliamp status --json | jq .track.title
|
|
|
|
# Pause from a tmux/cmux script
|
|
cliamp pause
|
|
|
|
# Load a playlist and start playing
|
|
cliamp load "Blade Runner" && cliamp play
|
|
```
|
|
|
|
## Headless Daemon Mode
|
|
|
|
Run cliamp without a TUI and drive it entirely over this IPC interface — useful for status bars, hotkey scripts, cron jobs, and embedded boxes. See [Headless Daemon Mode](headless.md) for setup, use cases, and example configs (Waybar, Hyprland, systemd, cron).
|
|
|
|
```sh
|
|
cliamp --daemon # no TUI, IPC only
|
|
cliamp --daemon --auto-play --playlist Lofi # start playing on launch
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
If cliamp is not running:
|
|
|
|
```
|
|
$ cliamp status
|
|
cliamp is not running (no socket at /Users/you/.config/cliamp/cliamp.sock)
|
|
```
|