Skip to content

ssh-streaming.md

Latest commit

 

History

History
91 lines (62 loc) · 2.34 KB

ssh-streaming.md

File metadata and controls

91 lines (62 loc) · 2.34 KB

SSH Streaming

Play music from a remote machine over SSH without mounting filesystems.

How It Works

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

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

The player runs ssh hostname cat /path/to/file.mp3 and feeds the output to the audio decoder. No temporary files, no filesystem mounts.

Creating SSH Playlists

Use --ssh HOST with playlist create to walk 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 discover audio files, then creates a TOML playlist with ssh:// prefixed paths.

TOML Format

SSH playlists look like regular playlists 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, which reads ~/.ssh/config. Host aliases, keys, ports, and ProxyJump all 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 works with all formats supported by the native decoders:

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

Formats requiring ffmpeg (.m4a, .wma) may not work over SSH since the ffmpeg decoder expects a seekable file.

Error Handling

Scenario Behavior
Host unreachable Player shows error, advances to next track
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

Mixing Local and SSH Tracks

A single playlist can mix 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"