SSH Streaming

Play music from a remote machine through SSH. You do not need to mount a filesystem.

How It Works

When a track path starts with ssh://, cliamp pipes audio through SSH with the system ssh binary:

ssh://hostname/absolute/path/to/file.mp3

The player runs ssh hostname cat /path/to/file.mp3 and sends the output to the audio decoder. It uses no temporary files or filesystem mounts.

Creating SSH Playlists

Use --ssh HOST with playlist create to scan a remote directory:

cliamp playlist create "Blade Runner" --ssh nas "/Volumes/Music/Blade Runner/"
# Created playlist "Blade Runner" (31 tracks, ssh://nas)

This runs ssh nas find /path -type f -name '*.mp3' ... to find audio files. It then creates a TOML playlist with ssh:// path prefixes.

TOML Format

SSH playlists use regular playlist format with ssh:// paths:

name = "Blade Runner"

[[track]]
path = "ssh://nas/Volumes/Music/Blade Runner/01 - Prologue.mp3"
title = "Prologue And Main Titles"

[[track]]
path = "ssh://nas/Volumes/Music/Blade Runner/02 - Voight Kampff.mp3"
title = "Voight Kampff Test"

SSH Configuration

cliamp uses the system ssh binary. It reads ~/.ssh/config. Host aliases, keys, ports, and ProxyJump work automatically:

# ~/.ssh/config
Host nas
    HostName 192.168.1.50
    User music
    IdentityFile ~/.ssh/nas_key

Host mac-mini-ts
    HostName 100.64.0.5

Supported Formats

SSH streaming supports formats that native decoders support:

.mp3 (native decoder)
.flac (native decoder)
.ogg / .opus (native decoder)
.wav (native decoder)

Formats that require ffmpeg (.m4a, .wma) might not work over SSH because the ffmpeg decoder expects a seekable file.

Error Handling

Scenario	Behavior
Host unreachable	The player shows an error and advances to the next track.
Auth failure	SSH uses `BatchMode=yes` and does not wait for password prompts.
Connection drops mid-stream	The player detects EOF and advances to the next track.
Unknown host key	The connection is rejected. Add the host to `~/.ssh/known_hosts` first, or configure it in `~/.ssh/config`.

Mixing Local and SSH Tracks

A playlist can contain local and SSH paths:

name = "Mixed"

[[track]]
path = "/local/path/track1.mp3"
title = "Local Track"

[[track]]
path = "ssh://nas/remote/path/track2.mp3"
title = "Remote Track"