amp

Guide · 06

Phone and remote control

Drive amp from a shell, from media keys, or from a phone — as a remote, or as a player of its own.

From the shell

These commands talk to the running daemon and return at once. They never start one.

amp --toggle                        # also --play, --pause, --stop, --next, --previous, --mute
amp --volume +5                     # relative; --volume 60 is absolute (up to 150)
amp --seek -10                      # seconds; --seek 1:30 jumps into the track
amp --speed 1.25                    # 0.5 to 2.0, pitch kept
amp --shuffle on                    # on, off, or toggle with no value
amp --repeat one                    # off, all, one
amp --open ~/playlists/mix.m3u8     # queue a playlist, or play a stream URL
amp --status                        # one line: what is playing
amp --status --json                 # everything, for scripts

They combine: amp --volume +5 --next --status. A tmux status line, a window-manager shortcut:

set -g status-right '#(amp --status 2>/dev/null)'
bindsym XF86AudioPlay exec amp --toggle

Media keys

amp answers the keyboard’s media keys and appears in the system’s Now Playing — through MPRIS on Linux, natively on macOS and Windows. Nothing to set up.

A phone or a browser

This one is off until you turn it on. In config.toml:

[remote_http]
enabled = true
host = "0.0.0.0"      # every interface; "127.0.0.1" keeps it on this machine
port = 8420

Then ask amp for the address and the pairing key:

amp --http-remote-info

Open the address on the phone, type the key once, and choose at the top of the page:

  • Speakers — a remote for this computer’s speakers: transport, volume, queue, library.
  • This device — the phone’s own queue, over the same libraries, played by the phone itself. The computer stays silent. Under Quality, pick the original files or a lighter stream (Opus or MP3, which need ffmpeg on the computer).

Each phone stays paired until it signs out. From the computer:

amp daemon devices                  # the paired phones and browsers, numbered
amp daemon forget 3                 # sign that one out

On the local network the traffic is plain HTTP. Turn it on only on a network you trust — or reach amp through a VPN or a proxy, below.

From outside the house

amp does no TLS itself. Put it behind something that does.

Tailscale (or WireGuard) already encrypts: keep host = "0.0.0.0" and set public_url = "http://mybox.tailnet-name.ts.net:8420".

Caddy on the same machine gets the certificate itself:

amp.example.org {
    reverse_proxy 127.0.0.1:8420
}
[remote_http]
enabled = true
host = "127.0.0.1"                       # only the proxy reaches amp
public_url = "https://amp.example.org"
trusted_proxies = ["127.0.0.1"]

With nginx, forward the WebSocket’s Upgrade and Connection headers for /ws.