Remote commands

rmpc provides powerful remote command capabilities that allow you to control a running rmpc instance from the command line. this is especially useful for scripting and window manager integration.

overview

the remote command system allows you to:

• emulate key presses (keybind) - trigger any keybind as if pressed in the interface
• switch tabs directly (switch-tab) - change to a specific tab without relying on keybinds
• send status messages - display custom messages in the status bar
• update configuration - modify theme and other settings remotely
• target specific instances - send commands to a particular rmpc process by pid

usage

all remote commands follow this pattern:

rmpc remote [--pid <pid>] <command> <args>

if --pid is not specified, the command will be sent to all running rmpc instances.

keybind command

the keybind command emulates pressing a key combination in the running rmpc interface.

syntax

rmpc remote keybind <key>

examples

# press 'p' (typically play/pause)
rmpc remote keybind p

common key examples

# basic navigation
rmpc remote keybind j  # move down
rmpc remote keybind k  # move up
rmpc remote keybind h  # move left
rmpc remote keybind l  # move right

# playback control
rmpc remote keybind p      # toggle play/pause
rmpc remote keybind s      # stop playback
rmpc remote keybind ">"    # next track
rmpc remote keybind "<"    # previous track

# tab switching (numbers)
rmpc remote keybind 1      # switch to queue tab
rmpc remote keybind 2      # switch to directories tab
rmpc remote keybind 3      # switch to artists tab
rmpc remote keybind 4      # switch to album artists tab
rmpc remote keybind 5      # switch to albums tab
rmpc remote keybind 6      # switch to playlists tab
rmpc remote keybind 7      # switch to search tab

# volume control
rmpc remote keybind "."    # volume up
rmpc remote keybind ","    # volume down

# seek control
rmpc remote keybind f      # seek forward
rmpc remote keybind b      # seek backward

# modes
rmpc remote keybind z      # toggle repeat
rmpc remote keybind x      # toggle random
rmpc remote keybind c      # toggle consume
rmpc remote keybind v      # toggle single

# help and info
rmpc remote keybind "~"       # Show help
rmpc remote keybind I         # Show current song info
rmpc remote keybind O         # Show outputs
rmpc remote keybind P         # Show decoders

Key Format Notes

For special keys, use the angle bracket format to ensure proper recognition:

# Correct formats for special keys
rmpc remote keybind "<CR>"     # Enter key
rmpc remote keybind "<Space>"  # Space key
rmpc remote keybind "<Esc>"    # Escape key
rmpc remote keybind "<Tab>"    # Tab key
rmpc remote keybind "<BS>"     # Backspace key

# Modifiers use angle brackets too
rmpc remote keybind "<C-p>"    # Ctrl+p
rmpc remote keybind "<S-CR>"   # Shift+Enter
rmpc remote keybind "<A-h>"    # Alt+h

switch-tab command

The switch-tab command provides a direct way to switch between tabs without relying on keybind configuration.

Syntax

rmpc remote switch-tab <tab-name>

Examples

# Switch to specific tabs
rmpc remote switch-tab "Queue"
rmpc remote switch-tab "Directories"
rmpc remote switch-tab "Artists"
rmpc remote switch-tab "Albums"
rmpc remote switch-tab "Playlists"
rmpc remote switch-tab "Search"
rmpc remote switch-tab "Lyrics"

# Works with custom tab names too
rmpc remote switch-tab "My Custom Tab"

# Tab names are case-insensitive
rmpc remote switch-tab "queue"     # same as "Queue"
rmpc remote switch-tab "ARTISTS"   # same as "Artists"
rmpc remote switch-tab "playlists" # same as "Playlists"

Tab Name Validation

The switch-tab command validates that the specified tab exists in your configuration using case-insensitive matching. This means you can use any capitalization you prefer - queue, Queue, QUEUE, etc. will all match the same tab.

If you try to switch to a non-existent tab, the command will fail with an error message listing all available tabs.

You can check your available tabs by looking at your configuration file or using rmpc config to see the configured tabs.

Other Remote Commands

Besides keybind, rmpc supports several other remote commands:

Status Messages

Display custom messages in the rmpc status bar:

# Show an info message for 5 seconds (default)
rmpc remote status "Hello from script!"

# Show an error message for 10 seconds
rmpc remote status --level error --timeout 10000 "Something went wrong"

# Show a warning message
rmpc remote status --level warn "Check your config"

Lyrics Index

Notify rmpc about new lyrics files:

# Tell rmpc to index a new .lrc file
rmpc remote indexlrc --path /path/to/song.lrc

Set Commands

Update configuration in a running rmpc instance:

# Update theme from file
rmpc remote set theme /path/to/new-theme.ron

# Update theme from stdin
cat new-theme.ron | rmpc remote set theme -

Targeting Specific Instances

If you have multiple rmpc instances running, you can target a specific one using the --pid option:

# Find rmpc processes
ps aux | grep rmpc

# Send command to specific instance
rmpc remote --pid 12345 keybind p
rmpc remote --pid 12345 switch-tab "Queue"
rmpc remote --pid 12345 status "Hello from specific instance"

Error Handling

Remote commands will fail silently if:

• No rmpc instance is running
• The specified PID doesn’t exist
• Invalid key format is provided
• Tab name doesn’t exist in your configuration (for switch-tab commands)

Note: Command execution errors (like invalid tab names) are logged in the running rmpc instance at the warn level, not displayed to the CLI caller. Check the rmpc logs for detailed error messages if commands aren’t working as expected.

To see these errors, you can:

• Run rmpc with debug logging: RUST_LOG=debug rmpc
• Check rmpc’s log output in your terminal
• Look for “Socket command execution failed” messages

Tips and Best Practices

• Use quotes for special characters: Always quote keys with special characters like ">" or "<" or "<Tab>"
• Check keybind configuration: The remote keybind command uses your configured keybinds from your config file
• Test interactively first: Try commands manually before adding them to scripts

See Also

• Keybind Configuration - Configure what keys do what
• Tab Configuration - Set up custom tab names
• CLI Reference - Full command reference