rmpc

https://mierak.github.io/rmpc/next/
Admin
rmpc is a software project that provides documentation for its various versions.
Tokens:10,703
Snippets:116
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Rmpc Configuration Example (RON)

Source: https://mierak.github.io/rmpc/next/configuration

Example of a Rmpc configuration file in RON format. It demonstrates how to set various parameters like address, password, and directories.

```config
address: "127.0.0.1:6600"
password: "your_mpd_password"
cache_dir: Some("/path/to/cache")
lyrics_dir: Some("/path/to/lyrics")
lyrics_offset_ms: 0
mpd_read_timeout_ms: 10000
mpd_write_timeout_ms: 5000
mpd_idle_read_timeout_ms: None
rewind_to_start_sec: None
keep_state_on_song_change: true
theme: Some("dark.ron")
volume_step: 5
max_fps: 30
```

--------------------------------

### Install and Run rmpc with Nix

Source: https://mierak.github.io/rmpc/next/try-without-install

Instructions for installing and running rmpc using the Nix package manager. rmpc is available in the 'unstable' channel.

```bash
nix run nixpkgs#rmpc -- --mpd-host localhost --mpd-port 6600
```

--------------------------------

### Example: Displaying Artist with Fallback

Source: https://mierak.github.io/rmpc/next/configuration/song-table

An example configuration for a song table column that displays the song's artist. If the artist metadata is missing, it defaults to 'Unknown Artist' with specified foreground and background colors.

```N/A
song_table_format: [
  {
    prop: "Artist",
    width: "100%",
    alignment: "Left",
    label: Some("Artist"),
    kind: Property(Artist),
    default: Text("Unknown Artist", style: Style(foreground_color: "red", background_color: "black")),
  }
]
```

--------------------------------

### Property Pane Example

Source: https://mierak.github.io/rmpc/next/configuration/tabs

An example of using the Property pane to display a specific song or MPD property.

```rmpc config
Property("current_song.title")
```

--------------------------------

### Try rmpc without installing

Source: https://mierak.github.io/rmpc/next/try-without-install

This command allows users to try the rmpc tool without a formal installation. It requires a working MPD installation.

```bash
curl -sSL https://raw.githubusercontent.com/lyokha/rmpc/main/rmpc | bash -s -- --mpd-host localhost --mpd-port 6600
```

--------------------------------

### Get Help for a Specific Rmpc Command

Source: https://mierak.github.io/rmpc/next/reference/cli-command-mode

Provides detailed help for a specific Rmpc command, including its usage, options, and expected parameters. Useful for understanding individual command functionalities.

```bash
rmpc toggle-output --help
```

--------------------------------

### Example keybinds_map definition

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Defines a mapping of keys to actions, showing how to bind single keys to specific commands. This structure is used for global, navigation, and queue-specific keybinds.

```config
global: { "p": Play, "s": Stop, "X": Stop, ...}
```

--------------------------------

### Add YouTube video to rmpc queue

Source: https://mierak.github.io/rmpc/next/guides/youtube

Adds a YouTube video to the rmpc playback queue from a given URL. Supports adding to a specific position in the queue. Requires yt-dlp to be installed and in the system's PATH.

```bash
rmpc addyt <youtube-url>

```

```bash
rmpc addyt --position <n|+n|-n> <youtube-url>

```

--------------------------------

### Desktop Notification Script Example

Source: https://mierak.github.io/rmpc/next/guides/on_song_change

An example bash script to display a desktop notification when a song changes in rmpc. It utilizes environment variables provided by rmpc, such as $TITLE and $ARTIST, to display song information. Assumes a notification daemon like 'dunst' is installed.

```bash
#!/bin/bash

notify-send "Now Playing: $TITLE" "$ARTIST"

```

--------------------------------

### LRC File Resolution - Same Path

Source: https://mierak.github.io/rmpc/next/configuration/lyrics

This example demonstrates how rmpc attempts to resolve an LRC file by looking for a file with the same name and a '.lrc' extension in the same directory as the music file. This method is checked first.

```bash
# Assuming music directory is /home/user/Music
# For song: /home/user/Music/artist/album/song.flac
# Rmpc will try to resolve: /home/user/Music/artist/album/song.lrc
```

--------------------------------

### Set rmpc Theme in Config

Source: https://mierak.github.io/rmpc/next/configuration/theme

Example of how to specify a custom theme in the rmpc configuration file. This involves editing the `theme` property.

```ron
theme = "my_custom_theme"
```

--------------------------------

### Automatic Lyrics Fetch Script Example

Source: https://mierak.github.io/rmpc/next/guides/on_song_change

A Python script designed to automatically download lyrics for the currently playing song from lrclib.net. It uses rmpc's environment variables like $TITLE, $ARTIST, and $LRC_FILE to find song details and save the lyrics. Requires the 'requests' library.

```python
import requests
import os
import sys

def fetch_lyrics(title, artist, lyrics_dir):
    try:
        response = requests.get(f"https://lrclib.net/api/lyrics/{artist}/{title}")
        response.raise_for_status()  # Raise an exception for bad status codes
        data = response.json()
        if data and 'lyrics' in data:
            lrc_content = data['lyrics']
            # Construct filename based on rmpc's expected LRC_FILE format if possible
            # For simplicity, using a generic name here.
            filename = f"{artist} - {title}.lrc"
            filepath = os.path.join(lyrics_dir, filename)
            with open(filepath, 'w', encoding='utf-8') as f:
                f.write(lrc_content)
            print(f"Lyrics saved to: {filepath}")
            # Update rmpc's LRC_FILE environment variable if possible, or rely on rmpc finding it
            # os.environ['LRC_FILE'] = filepath # This won't affect the parent rmpc process
            return True
        else:
            print(f"No lyrics found for '{title}' by '{artist}'")
            return False
    except requests.exceptions.RequestException as e:
        print(f"Error fetching lyrics: {e}")
        return False
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
        return False

if __name__ == "__main__":
    # Get environment variables set by rmpc
    title = os.environ.get('TITLE')
    artist = os.environ.get('ARTIST')
    lyrics_dir = os.environ.get('LYRICS_DIR') # Assumes LYRICS_DIR is configured in rmpc config

    if not all([title, artist, lyrics_dir]):
        print("Error: Missing required environment variables (TITLE, ARTIST, LYRICS_DIR). Ensure rmpc is configured correctly.")
        sys.exit(1)

    if not os.path.exists(lyrics_dir):
        os.makedirs(lyrics_dir)
        print(f"Created lyrics directory: {lyrics_dir}")

    fetch_lyrics(title, artist, lyrics_dir)

```

--------------------------------

### Configure rmpc Progress Bar Symbols

Source: https://mierak.github.io/rmpc/next/configuration/theme

Defines the characters used to construct the progress bar. Includes start, elapsed, thumb, track, and end symbols.

```ron
progress_bar:
  symbols: ["[", "=", ">", " ", "]"]
```

--------------------------------

### Configure Pane Layout for Cava

Source: https://mierak.github.io/rmpc/next/configuration/cava

This snippet shows how to add a Cava pane to your Rmpc layout, alongside existing panes like the queue and album art. This configuration is part of the pane layout setup in your `config.ron` file. Consult the Panes documentation for more details on pane management.

```toml
[ui.tabs]
[ui.tabs.default]
active = "queue"

[[ui.tabs.default.panes]]
key = "queue"

[[ui.tabs.default.panes]]
key = "album_art"

[[ui.tabs.default.panes]]
key = "cava"

[ui.split]
orientation = "horizontal"
sizes = ["1fr", "2fr"]

[ui.split.left]
orientation = "vertical"
sizes = ["1fr", "1fr"]

[ui.split.left.top]
key = "queue"

[ui.split.left.bottom]
key = "album_art"

[ui.split.right]
key = "cava"
```

--------------------------------

### LRC File Resolution - Different Lyrics Directory

Source: https://mierak.github.io/rmpc/next/configuration/lyrics

This example shows how rmpc resolves an LRC file when a separate 'lyrics_dir' is configured. Rmpc will look for the LRC file within this specified directory, preserving the relative path structure from the music file.

```bash
# Assuming music directory is /home/user/Music and lyrics_dir is /home/user/.lyrics
# For song: /home/user/Music/artist/album/song.flac
# Rmpc will try to resolve: /home/user/.lyrics/artist/album/song.lrc
```

--------------------------------

### Disable Album Art Fetching by Protocol

Source: https://mierak.github.io/rmpc/next/configuration/album-art

This configuration specifies a list of protocols for which album art should not be fetched or displayed. If the song path starts with any of these protocols, the album art will be skipped. An empty array enables all protocols. The default is to disable fetching for 'http://' and 'https://'.

```yaml
disabled_protocols: string[]
```

--------------------------------

### Track Song Play Count Script Example

Source: https://mierak.github.io/rmpc/next/guides/on_song_change

A bash script to increment a song's play count sticker. This script requires 'jq' for JSON processing and is intended to be called by rmpc's 'on_song_change' property. It reads the current song's path, updates its play count in a sticker file, and relies on MPD's sticker functionality.

```bash
#!/bin/bash

# Assumes sticker_file is configured in mpd.conf and points to a JSON file
# Example: {"~/.config/rmpc/stickers.json"}

# Get current song info (assuming $FILE is available from rmpc)
if [ -n "$FILE" ]; then
  # Increment play count for the current song file
  # This is a simplified example, a real implementation would need robust handling
  # of JSON file updates and error checking.
  # Example using jq to update a hypothetical sticker JSON:
  # jq --arg file "$FILE" '. + {"$file": (.["$file"] // 0) + 1}' ~/.config/rmpc/stickers.json > ~/.config/rmpc/stickers.json.tmp && mv ~/.config/rmpc/stickers.json.tmp ~/.config/rmpc/stickers.json
  echo "Incrementing play count for: $FILE"
fi

```

--------------------------------

### Partition Management

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Keybinds for managing music library partitions, including opening a partition management modal and switching to or creating partitions.

```keybindings
Partition(): Open partition management modal
Partition(name: "mypart", autocreate: true): Switch to and create partition "mypart"
```

--------------------------------

### Try rmpc on NixOS 24.05

Source: https://mierak.github.io/rmpc/next/try-without-install

A specific command to try rmpc on NixOS 24.05, leveraging Nix for package management.

```bash
nix run 'nixpkgs#rmpc' --impure --expr '<nixpkgs/nixos-24.05>' -- --mpd-host localhost --mpd-port 6600
```

--------------------------------

### View Rmpc Help

Source: https://mierak.github.io/rmpc/next/reference/cli-command-mode

Displays all available commands for the Rmpc CLI. This is the primary command to understand the tool's capabilities.

```bash
rmpc --help
```

--------------------------------

### Bootstrap Rmpc Configuration

Source: https://mierak.github.io/rmpc/next/configuration

Command to bootstrap the Rmpc configuration file. This is the initial step to create a default configuration.

```bash
rmpc --bootstrap-config
```

--------------------------------

### Add Options and Context Menu

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Keybinds to add items with specified options and to display a context menu for available actions on the current item(s).

```keybindings
AddOptions(): Add items with specified options
ContextMenu(): Show context menu for current item(s)
```

--------------------------------

### Set Text and Preview Styles

Source: https://mierak.github.io/rmpc/next/configuration/theme

Configures the foreground color for basic text and defines custom styles for song metadata labels and group headers in browser previews.

```configuration
text_color: color
preview_label_style: <style>
preview_metadata_group_style: <style>
```

--------------------------------

### Configure on_resize Action

Source: https://mierak.github.io/rmpc/next/configuration

Defines a command to be executed when the RMPC window is resized. The first element is the command, and subsequent elements are its arguments. An empty array means no command is executed.

```shell
on_resize: ["notify-send", "rmpc resized!"]
```

--------------------------------

### Search YouTube videos with rmpc

Source: https://mierak.github.io/rmpc/next/guides/youtube

Searches for YouTube videos using specified search terms and adds the first result to the rmpc playback queue. Allows specifying an optional position for the added video. Requires yt-dlp.

```bash
rmpc searchyt "search terms"

```

```bash
rmpc searchyt --position <n|+n|-n> "search terms"

```

--------------------------------

### Configure on_song_change Action

Source: https://mierak.github.io/rmpc/next/configuration

Defines a command to be executed when the song changes. The first element is the command, and subsequent elements are its arguments. An empty array means no command is executed.

```shell
on_song_change: ["notify-send", "song changed!"]
```

--------------------------------

### Interface Navigation and Selection

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Keybindings for navigating the RMPC interface, selecting items, managing queues, and interacting with search and input fields. These include cursor movement, selection, and confirmation actions.

```keybindings
`<C-c>` / `Esc`: Close / Cancel current action
`k`: Up / Move cursor up
`l`: Right / Move cursor right
`<Space>`: Select / Mark current item as selected
`<C-Space>`: InvertSelection / Invert selection of items
`Enter`: Confirm / Confirm action or enter directory/play song
`K`: MoveUp / Move item up in queue
`J`: MoveDown / Move item down in queue
`g`: Top / Jump to the top of the list
`G`: Bottom / Jump to the bottom of the list
`<C-n>`: NextResult / Jump to next search result
`N`: PreviousResult / Jump to previous search result
`j`: Down / Move cursor down
`D`: Delete / Delete item or clear queue
`<C-u>`: UpHalf / Jump half screen up
`<C-d>`: DownHalf / Jump half screen down
`PageUp`: PageUp / Jump one screen up
`PageDown`: PageDown / Jump one screen down
`i`: FocusInput / Focus an input textbox
`/`: EnterSearch / Enter search mode
`h`: Left / Move cursor left
`r`: Rename / Rename playlist
`a`: Add / Add item to queue
`A`: AddAll / Add all items to queue
`B`: ShowInfo / Show item info in a modal
```

--------------------------------

### Bootstrap rmpc Config File

Source: https://mierak.github.io/rmpc/next/configuration/theme

Command to bootstrap the rmpc configuration file. This is the initial step to enable theme customization.

```bash
rmpc --generate-config
```

--------------------------------

### Configure Album Art Method

Source: https://mierak.github.io/rmpc/next/configuration/album-art

This configuration option sets the rendering method for displaying album art. Supported methods include Kitty, UeberzugWayland, UeberzugX11, Block, and None. 'Auto' is the default, attempting Kitty first, then Ueberzug. 'Block' falls back to ANSI if truecolor is not supported. 'None' disables album art display.

```yaml
method: Kitty | Iterm2 | Sixel | UeberzugWayland | UeberzugX11 | Block | None | Auto
```

--------------------------------

### Configure Header Display

Source: https://mierak.github.io/rmpc/next/configuration/theme

Sets up the content and layout of the window header, which can include current song information, player state, and custom widgets.

```configuration
header: <header[]>
```

--------------------------------

### Global Playback and Navigation Controls

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Global keybindings that control playback, tab navigation, library updates, and playback modes like repeat and consume. These functions are accessible across most of the RMPC interface.

```keybindings
`q`: Quit / Exit rmpc
`~`: ShowHelp / Show help modal
`:`: CommandMode / Enter command mode
`q`: ShowHelp / Show keybinds modal
`I`: ShowCurrentSongInfo / Show song metadata
`O`: ShowOutputs / Show MPD outputs config
`P`: ShowDecoders / Show MPD decoder plugins
`z`: ToggleRepeat / Toggle repeat
`x`: ToggleRandom / Toggle random playback
`c`: ToggleConsume / Remove song after playing
`v`: ToggleSingle / Control single track playback behavior
`p`: TogglePause / Pause or unpause playback
`s`: Stop / Stop playback
`.`: VolumeUp / Increase volume
`,`: VolumeDown / Decrease volume
`f`: SeekForward / Seek forward in the current track
`b`: SeekBack / Seek backward in the current track
`>`: NextTrack / Play the next track
`<`: PreviousTrack / Play the previous track
`Right` / `Tab`: NextTab / Switch to the next tab
`Left` / `<S-Tab>`: PreviousTab / Switch to the previous tab
`1`: SwitchToTab("Queue") / Switch to Queue tab
`2`: SwitchToTab("Directories") / Switch to Directories tab
`3`: SwitchToTab("Artists") / Switch to Artists tab
`4`: SwitchToTab("Album") / Switch to Albums tab
`5`: SwitchToTab("Playlists") / Switch to Playlists tab
`6`: SwitchToTab("Search") / Switch to Search tab
`R`: AddRandom / Add random songs to the queue
`u`: Update / Update music library
`U`: Rescan / Rescan music library
```

--------------------------------

### Queue Management Keybinds

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Provides keybindings for common queue operations such as saving, clearing, playing, adding to playlists, deleting, jumping to the current song, and shuffling.

```text
Queue Keybinds:
<C-s>: Save current queue as a new playlist
D: DeleteAll (Clear current queue)
Enter: Play song under cursor
a: AddToPlaylist (Add song under cursor to an existing playlist)
d: Delete (Remove song under cursor from the queue)
C: JumpToCurrent (Moves cursor to currently playing song)
X: Shuffle (Shuffles the whole queue or selected range(s))
```

--------------------------------

### AddOptions for Queue Management

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Configurable keybind to add items to the queue. Allows specifying single/all items, position, and autoplay behavior. A modal is displayed if no configuration is provided. Supports adding marked items or all items in a directory.

```text
AddOptions(kind: <kind>)
<kind> can be Modal (with label and action config) or Action (with single action config).
Possible positions: StartOfQueue, EndOfQueue, BeforeCurrentSong, AfterCurrentSong, Replace.
Autoplay options: None, First, Hovered, HoveredOrFirst.
'all' parameter: true (add all items) or false (add marked items/hovered item).
```

--------------------------------

### Configure Song Table and Browser Formats

Source: https://mierak.github.io/rmpc/next/configuration/theme

Defines the structure and display format for songs in the table and browser panes. Styles are ignored in the browser format.

```configuration
song_table_format: <song_table_format>
browser_song_format: <song_table_format>
```

--------------------------------

### Configure Rmpc and Cava Settings

Source: https://mierak.github.io/rmpc/next/configuration/cava

This snippet demonstrates the configuration for Rmpc and Cava, specifically focusing on setting the input to match the MPD FIFO path. These settings are passed directly to Cava. Refer to Cava's documentation for additional options. This configuration should be placed in your `config.ron` file.

```toml
[visualizer.cava]
input = "/tmp/mpd.fifo"
framerate = 60

[ui.pane.cava]
visible = true
```

--------------------------------

### SingleV2 Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Configures the single playback state with customizable labels for on/off and one-shot states. Similar to StateV2.

```text
kind: Property(Status(SingleV2(on_label: "<your label>", off_label: "<your label>", oneshot_label: "<your label>", on_style: <style>, off_style: <style>, oneshot_style: <style>)))
```

--------------------------------

### Volume Widget

Source: https://mierak.github.io/rmpc/next/configuration/header

A predefined widget to display volume with percentage and bars. Offers a more visual representation than a simple number.

```text
kind: Property(Widget(Volume))
```

--------------------------------

### Song Table Column Configuration

Source: https://mierak.github.io/rmpc/next/configuration/song-table

Defines a single column within the song table. Properties like 'prop', 'width', 'alignment', and 'label' configure its appearance and content. Fallback values are used when properties are not explicitly defined.

```N/A
song_table_format: <song_table_column[]>
```

```N/A
song_table_column:
  prop: <property>
  width: "<string>"
  alignment: Left | Right | Center
  label: None | Some("<string>")
```

--------------------------------

### Configure Album Display Mode

Source: https://mierak.github.io/rmpc/next/configuration

Determines how albums are displayed in the Artists and AlbumArtists panes. Options include splitting by date or showing only the name.

```config
album_display_mode:
  SplitByDate
  NameOnly
```

--------------------------------

### Displaying Stickers with Sticker()

Source: https://mierak.github.io/rmpc/next/configuration/stickers

Demonstrates how to access and display MPD stickers within rmpc using the Sticker() property. Ensure that MPD is configured to support stickers.

```rmpc
Sticker("<name>")
```

--------------------------------

### Keybind syntax with modifiers

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Illustrates the syntax for creating keybinds, including single keys, uppercase keys, and combinations with modifier keys like Ctrl and Alt. Special keys are enclosed in angle brackets.

```config
a
A
<C-a>
<C-A>
<Tab>
<A-x>
```

--------------------------------

### Execute Command on Rmpc Resize

Source: https://mierak.github.io/rmpc/next/guides/on_resize

This snippet demonstrates how to configure rmpc to execute a command whenever the rmpc window is resized. It utilizes the `on_resize` property in the configuration file and highlights special environment variables available to the script, such as $PID, $COLS, and $ROWS.

```shell
# Example script to be saved as ~/.config/rmpc/scripts/onresize
# This script changes the theme based on terminal size

if [ "$COLS" -lt 80 ]; then
  # Set a compact theme for smaller terminals
  echo "theme compact"
elif [ "$COLS" -gt 120 ]; then
  # Set a wide theme for larger terminals
  echo "theme wide"
else
  # Default theme for medium-sized terminals
  echo "theme default"
fi

# Example using $PID to target a specific rmpc instance (if applicable)
# echo "remote $PID --set-option theme dark"
```

--------------------------------

### Volume Pane with Slider Configuration

Source: https://mierak.github.io/rmpc/next/configuration/tabs

Sets up a Volume pane and configures its appearance or behavior using a Slider.

```rmpc config
Volume(kind = Slider({
    # Slider configuration options here
}))
```

--------------------------------

### Define Highlight and Border Styles

Source: https://mierak.github.io/rmpc/next/configuration/theme

Sets the visual styles for highlighted items and borders within the application, including the style for the highlight border.

```configuration
highlighted_item_style: <style>
current_item_style: <style>
borders_style: <style>
highlight_border_style: <style>
```

--------------------------------

### Set Multiple Tag Resolution Strategy

Source: https://mierak.github.io/rmpc/next/configuration/theme

Determines how to handle song tags with multiple values. Options include taking all values, the first, the last, or a specific Nth value.

```configuration
multiple_tag_resolution_strategy: All | First | Last | Nth(<number>)
```

--------------------------------

### RMPC Component Definition and Usage

Source: https://mierak.github.io/rmpc/next/configuration/layout

Illustrates how to define and reuse UI components in RMPC. Components are defined as a map of string to Pane, Split, or Component, and can be included in layouts or other components for modularity.

```plaintext
components: Map<string, Pane | Split | Component>
// Example:
components: {
  state: Pane,
  title: Pane,
  volume: Pane
}

header: Component { // Uses the above components
  state,
  title,
  volume
}

layout: Pane { // Uses the header component
  header
}
```

--------------------------------

### ConsumeV2 Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Configures the consume state with customizable labels for on/off and one-shot states. Supports one-shot state from MPD 0.24.0.

```text
kind: Property(Status(ConsumeV2(on_label: "<your label>", off_label: "<your label>", oneshot_label: "<your label>", on_style: <style>, off_style: <style>, oneshot_style: <style>)))
```

--------------------------------

### Rate Song Functionality

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Allows setting the rating for the currently playing song or songs under the cursor. Supports direct value setting, like/neutral/dislike states, and modal displays for rating selection. Min/max ratings default to 0 and 10.

```text
Rate(kind: <kind>, current: <bool>, min_rating: <number>, max_rating: <number>)
<kind> can be Modal, Value, Like(), Neutral(), or Dislike().
```

--------------------------------

### ExternalCommand for binding scripts

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Shows how to bind custom shell scripts or commands to keybinds. The command can accept arguments and receive environment variables related to rmpc's state and song information.

```config
ExternalCommand(command: ["/path/to/my/script.sh", "arg1", "arg2"], description: "Description to show in Help modal.")
```

--------------------------------

### Display Sticker from Song Metadata (Sticker Kind)

Source: https://mierak.github.io/rmpc/next/configuration/header

Shows a sticker associated with the currently playing song, similar to how stickers are displayed in the song table. Requires a sticker key to identify the desired sticker.

```rmpc
kind: Sticker("album_cover")
```

--------------------------------

### Song Rating Configuration

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

Keybinding for rating songs, which can be configured to rate the current song or selected songs. It can also display a modal for rating if no specific configuration is provided.

```keybindings
`Rate()`: Set song rating
```

--------------------------------

### RandomV2 Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Configures the random playback state with customizable labels for on/off states. Similar to StateV2.

```text
kind: Property(Status(RandomV2(on_label: "<your label>", off_label: "<your label>", on_style: <style>, off_style: <style>)))
```

--------------------------------

### RepeatV2 Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Configures the repeat state with customizable labels for on/off states. Similar to StateV2.

```text
kind: Property(Status(RepeatV2(on_label: "<your label>", off_label: "<your label>", on_style: <style>, off_style: <style>)))
```

--------------------------------

### Set Default Album Art Path

Source: https://mierak.github.io/rmpc/next/configuration/album-art

Allows setting a default image file to be used as album art. This can be configured directly or potentially within a theme. Options are 'None' to use no default or 'Some("<string>")' to specify a file path.

```yaml
default_album_art_path: None | Some("<string>")
```

--------------------------------

### Property Definition for Song Table Columns

Source: https://mierak.github.io/rmpc/next/configuration/song-table

Specifies the data source and styling for a song table column. It includes the 'kind' of data to display, optional 'style' adjustments, and a 'default' value to use if the primary data is missing.

```N/A
property:
  kind: <property_kind>
  style: <style>
  default: <property>
```

--------------------------------

### QueueLength Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Displays the number of songs in the queue. The 'thousands_separator' parameter is optional and defaults to ','.

```text
kind: Property(Status(QueueLength(thousands_separator: ",")))
```

--------------------------------

### Property Pane Configuration

Source: https://mierak.github.io/rmpc/next/configuration/tabs

Configures the Property Pane, which can display AlbumArt and Queue panes. It also includes a Property pane that can show StateV2, ProgressBar, and Elapsed/Duration status. The pane supports scrolling if content exceeds its defined area, with scroll_speed controlling the cycle rate.

```text
pane: Pane(Property(content: <property>[], align: Left | Right | Center, scroll_speed: <number>))
```

--------------------------------

### Query rmpc State (query) - rmpc

Source: https://mierak.github.io/rmpc/next/guides/remote-commands

The `query` command retrieves information from a running rmpc instance. Multiple queryable items can be specified, and the response is a JSON object concatenating all results. Currently, 'activetab' is supported.

```shell
# Example: Query the active tab
rmpc query --pid <PID> activetab

# Example: Query multiple items (if more are supported in the future)
rmpc query activetab other_info
```

--------------------------------

### Scan Status Widget

Source: https://mierak.github.io/rmpc/next/configuration/header

A predefined widget that shows a loading spinner when the MPD database is being updated.

```text
kind: Property(Widget(ScanStatus))
```

--------------------------------

### Configure rmpc Default Album Art

Source: https://mierak.github.io/rmpc/next/configuration/theme

Sets a default album art path for songs that do not have associated album art. Uses an optional string.

```ron
default_album_art_path: Some("/path/to/default/art.png")
default_album_art_path: None
```

--------------------------------

### Property Kinds for Displaying Song Metadata

Source: https://mierak.github.io/rmpc/next/configuration/song-table

Defines the types of data that can be displayed in a song table column. Supported kinds include static Text, grouping of multiple properties (Group), specific song metadata (Property), and MPD stickers (Sticker).

```N/A
property_kind:
  Text("<string>")
  Group(<property>[] | <group>[] )
  Property(File | Filename | FileExtension | Title | Artist | Album | Duration | Disc | Position | Other("<tag_name>"))
  Sticker("<sticker_key>")
```

--------------------------------

### Directory Sorting Configuration (rmpc)

Source: https://mierak.github.io/rmpc/next/configuration

Configures how entries are sorted in the directories pane. Supports sorting by format, modified time, and custom sort formats. Options include grouping by type and reversing the order.

```rmpc config
directories_sort: ModifiedTime(..) | Format(..) | SongFormat(..)
```

```rmpc config
Format - Songs are sorted by their displayed format.
```

```rmpc config
SortFormat - Similar to `Format` but songs are sorted by browser_song_sort.
```

```rmpc config
ModifiedTime - Entries are sorted by their last modified time.
```

```rmpc config
Defaults to `SortFormat(group_by_type: true, reverse: false)`.
```

--------------------------------

### Configure Album Sort Order

Source: https://mierak.github.io/rmpc/next/configuration

Sets the sorting criteria for albums in the Artists and AlbumArtists panes. Albums can be sorted by name or date.

```config
album_sort_by:
  Name
  Date
```

--------------------------------

### Rmpc Style Configuration

Source: https://mierak.github.io/rmpc/next/configuration/style-color

Defines the structure for styling text in rmpc, including foreground color, background color, and text modifiers. Properties can be omitted or set to None.

```rust
struct Style {
    fg: Option<Color>,
    bg: Option<Color>,
    modifiers: Option<Vec<Modifier>>,
}

enum Color {
    Ansi(String),
    Hex(String),
    Rgb(String),
    Indexed(String),
}

enum Modifier {
    Bold,
    Dim,
    Italic,
    Underlined,
    Reversed,
    CrossedOut,
}
```

--------------------------------

### Display Player State with Custom Labels (Status StateV2)

Source: https://mierak.github.io/rmpc/next/configuration/header

Customizes the labels for the player's state (playing, paused, stopped). Allows for specific text and styles for each state, with defaults provided if not explicitly set.

```rmpc
kind: Property(Status(StateV2(playing_label: "Playing", paused_label: "Paused", stopped_label: "Stopped")))
```

--------------------------------

### Configure rmpc Cava Visualizer

Source: https://mierak.github.io/rmpc/next/configuration/theme

Settings for the Cava music visualizer, allowing customization of its appearance. More details are available on the Cava page.

```ron
cava:
  # Cava specific configuration options here
```

--------------------------------

### Display Song Title in Header (Property Kind)

Source: https://mierak.github.io/rmpc/next/configuration/header

Configures a header property to display the title of the currently playing song. This utilizes the Property kind to fetch and show song metadata.

```rmpc
kind: Property(Song(Title))
```

--------------------------------

### Configure Pane Borders

Source: https://mierak.github.io/rmpc/next/configuration/tabs

Demonstrates how to set specific borders (e.g., left and right) for a pane within a tab.

```rmpc config
Split(
    borders = LEFT | RIGHT,
    panes = [
        Pane(pane = Queue)
    ]
)
```

--------------------------------

### Configure Browser Song Sorting

Source: https://mierak.github.io/rmpc/next/configuration

Specifies the properties used to sort songs within browser panes. It's a list of song properties, with Disc and Track numbers being primary sorting keys.

```config
browser_song_sort: ["Disc", "Track", "Artist", "Title"]
```

--------------------------------

### QueueTimeTotal Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Displays the total duration of all songs in the queue. The 'separator' parameter controls formatting.

```text
kind: Property(Status(QueueTimeTotal(separator: ",")))
```

--------------------------------

### Display Player Volume in Header (Property Kind)

Source: https://mierak.github.io/rmpc/next/configuration/header

Configures a header property to show the current volume level of the player. This relies on the Property kind to retrieve player status information.

```rmpc
kind: Property(Status(Volume))
```

--------------------------------

### Define rmpc Layout Configuration

Source: https://mierak.github.io/rmpc/next/configuration/theme

Configuration for the base layout of the rmpc application, determining the placement of various components.

```ron
layout: Split
layout:
  top: Pane
  bottom: Pane
```

--------------------------------

### Configure MPD for Cava Output

Source: https://mierak.github.io/rmpc/next/configuration/cava

This snippet shows how to configure MPD (Music Player Daemon) to output data to a FIFO, which is necessary for Cava to read and visualize music. Ensure this configuration is placed in your `mpd.conf` file.

```shell
audio_output {
    type        "fifo"
    name        "my_fifo"
    path        "/tmp/mpd.fifo"
    format      "44100:16:2"
}
```

--------------------------------

### RMPC Layout Configuration Structure

Source: https://mierak.github.io/rmpc/next/configuration/layout

Defines the structure for RMPC layouts, which can be a single Pane or Split. Panes can contain specific UI elements or a special TabContent pane. Pane sizes can be percentages or terminal cell counts.

```plaintext
layout: Pane | Split | Component
Pane: AlbumArt | Lyrics | ProgressBar | Header | Tabs | TabContent
Pane sizes: "100%" or "5"
```

--------------------------------

### Playlist Visibility in Browser (rmpc)

Source: https://mierak.github.io/rmpc/next/configuration

Determines whether playlists are shown in the browser. Options include showing all, none, or only non-root playlists.

```rmpc config
show_playlists_in_browser: All | None | NonRoot
```

```rmpc config
`All` - Show all playlists
```

```rmpc config
`None` - Do not show playlists
```

```rmpc config
`NonRoot` - Show playlists everywhere except the root directory.
```

```rmpc config
Defaults to `NonRoot`.
```

--------------------------------

### Rmpc Color Formats

Source: https://mierak.github.io/rmpc/next/configuration/style-color

Illustrates the various formats accepted for color representation in rmpc, including 16 ANSI colors, Hex values, RGB values, and 8-bit indexed colors.

```rust
// ANSI Colors
let fg_red = Color::Ansi("red".to_string());
let fg_gray = Color::Ansi("gray".to_string());

// Hex Color
let fg_blue_hex = Color::Hex("#0000ff".to_string());

// RGB Color
let fg_green_rgb = Color::Rgb("rgb(0, 255, 0)".to_string());

// Indexed Color
let fg_custom_indexed = Color::Indexed("17".to_string());
```

--------------------------------

### ActiveTab Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Displays the currently active tab.

```text
kind: Property(Status(ActiveTab))
```

--------------------------------

### Control Rmpc Instance Remotely

Source: https://mierak.github.io/rmpc/next/reference/cli-command-mode

Allows external scripts or terminal sessions to control a running Rmpc instance. Useful for window manager integration, media key bindings, automation scripts, and headless control.

```bash
rmpc remote
```

--------------------------------

### Configure rmpc Song Table Album Separator

Source: https://mierak.github.io/rmpc/next/configuration/theme

Determines if albums in the song queue should be visually separated. Separation occurs when album artist or album differs from the previous song.

```ron
song_table_album_separator: Underline
```

--------------------------------

### Reflecting Changes to Playlist (rmpc)

Source: https://mierak.github.io/rmpc/next/configuration

Configures whether changes made to the queue are reflected in the last loaded playlist. Requires MPD version 0.24.0 or newer.

```rmpc config
reflect_changes_to_playlist: <bool>
```

```rmpc config
Defaults to false.
```

--------------------------------

### Switch Tabs (switchtab) - rmpc

Source: https://mierak.github.io/rmpc/next/guides/remote-commands

The `switchtab` command allows direct switching between tabs. It performs case-insensitive matching against configured tab names. If a tab does not exist, an error message listing available tabs will be returned.

```shell
# Example: Switch to 'queue' tab (case-insensitive)
rmpc switchtab --pid <PID> queue

# Example: Switch to a tab with spaces in its name
rmpc switchtab "My Queue"
```

--------------------------------

### Configure Browser Column Widths

Source: https://mierak.github.io/rmpc/next/configuration/theme

Sets the percentage width for columns displayed in the browser tab. It accepts an array of three numbers representing the width of each column.

```configuration
browser_column_widths: [number, number, number]
```

--------------------------------

### States Widget

Source: https://mierak.github.io/rmpc/next/configuration/header

A predefined widget for styling active and inactive states of various MPD features (Repeat, Random, Consume, Single). Allows custom styling for states and separators.

```text
kind: Property(Widget(States(active_style: <style>, separator_style: <style>)))
```

--------------------------------

### Update Configuration (set) - rmpc

Source: https://mierak.github.io/rmpc/next/guides/remote-commands

The `set` command enables remote modification of rmpc's configuration, such as themes and other settings. This is useful for dynamic configuration changes.

```shell
# Example: Update the theme to 'dark'
rmpc set theme dark
```

--------------------------------

### Control rmpc Song Table Header Visibility

Source: https://mierak.github.io/rmpc/next/configuration/theme

Toggles the display of the song table header. Defaults to true.

```ron
show_song_table_header: false
```

--------------------------------

### LRC File Format - Metadata Tags

Source: https://mierak.github.io/rmpc/next/configuration/lyrics

Metadata tags in LRC files provide information about the song, such as artist, title, and album. These tags are crucial for rmpc to match lyrics to songs. The 'offset' tag allows for time adjustments.

```lrc
[ar:Artist Name]
[ti:Song Title]
[al:Album Name]
[au:Author Name]
[length:3:45]
[offset:-500]
```

--------------------------------

### QueueTimeRemaining Configuration

Source: https://mierak.github.io/rmpc/next/configuration/header

Shows the remaining time in the queue, including the current song and subsequent songs. The 'separator' parameter controls formatting.

```text
kind: Property(Status(QueueTimeRemaining(separator: ",")))
```

--------------------------------

### Display Song Duration in Header (Property Kind)

Source: https://mierak.github.io/rmpc/next/configuration/header

Sets a header property to display the duration of the currently playing song. This uses the Property kind to access song metadata.

```rmpc
kind: Property(Song(Duration))
```

--------------------------------

### External Command Binding

Source: https://mierak.github.io/rmpc/next/configuration/keybinds

A special keybind that allows users to bind external commands to a key. Further details can be found in the ExternalCommand documentation.

```keybindings
ExternalCommand: Bind external commands to a key
```

--------------------------------

### Display Static Text in Header (Text Kind)

Source: https://mierak.github.io/rmpc/next/configuration/header

Configures a header property to display a fixed string. Useful for fallback text when song metadata is missing, like showing 'Unknown Album' if the album tag is not available.

```rmpc
kind: Text("Unknown Album")
```

--------------------------------

### Target Specific rmpc Instances (--pid)

Source: https://mierak.github.io/rmpc/next/guides/remote-commands

When multiple rmpc instances are running, the `--pid` option allows you to direct commands to a specific process. This ensures commands are executed on the intended instance.

```shell
# Example: Send 'keybind' command to a specific PID
rmpc --pid 12345 keybind '<space>'
```

--------------------------------

### Configure Tag Separator

Source: https://mierak.github.io/rmpc/next/configuration/theme

Specifies the separator string used when a song tag has multiple values. The default separator is '|'.

```configuration
format_tag_separator: "<string>"
```

--------------------------------

### Set Background Color

Source: https://mierak.github.io/rmpc/next/configuration/theme

Defines the background color for different parts of the application window, including the main window, header, and modal dialogs.

```configuration
background_color: color
header_background_color: color
modal_background_color: color
```

--------------------------------

### Control Lyrics Timestamp Visibility

Source: https://mierak.github.io/rmpc/next/configuration/theme

Determines whether timestamps are displayed alongside lyrics in the lyrics pane.

```configuration
lyrics.timestamp: true | false
```

--------------------------------

### Define a Tab with a Pane

Source: https://mierak.github.io/rmpc/next/configuration/tabs

A basic structure for defining a single tab with a specified pane. The tab has a name and a content pane.

```rmpc config
tab(
    name = "My Tab",
    pane = Pane(AlbumArt)
)
```

--------------------------------

### Emulate Key Presses (keybind) - rmpc

Source: https://mierak.github.io/rmpc/next/guides/remote-commands

The `keybind` command emulates pressing a key combination in the running rmpc interface. Ensure special keys are enclosed in angle brackets and quoted if they contain special characters.

```shell
# Example: Emulate Ctrl+P
rmpc keybind --pid <PID> '<Ctrl>+p'

# Example: Emulate '>'
rmpc keybind '<>'
```

--------------------------------

### Define rmpc Browser Symbols

Source: https://mierak.github.io/rmpc/next/configuration/theme

Customizes the symbols used in various browser panes, such as for artists, search results, and selected items.

```ron
symbols:
  song: "♪"
  dir: "D"
  marker: "*"
  ellipsis: "..."
```

--------------------------------

### Volume Pane Slider Configuration

Source: https://mierak.github.io/rmpc/next/configuration/tabs

Defines the Volume Pane, which currently only supports a Slider kind. This slider is interactive and allows volume adjustment via clicking or scroll wheel. It supports customization of symbols for different parts of the slider and styles for the track, filled portion, and thumb.

```text
Volume: Volume(kind: Slider(<config>))
```

```text
kind: Slider(symbols: <symbols[]>, track_style: <style>, filled_style: <style>, thumb_style: <style>)
```

```text
symbols - Array of 5 strings defining the visual elements: [start, filled, thumb, empty, end]
  * start - Symbol at the beginning of the slider (default: ”♪”)
  * filled - Symbol for the filled portion (default: ”─”)
  * thumb - Symbol for the current position indicator (default: ”●”)
  * empty - Symbol for the empty portion (default: ”─”)
  * end - Symbol at the end of the slider (default: ”♫”)
```

--------------------------------

### Control Modal Backdrop Visibility

Source: https://mierak.github.io/rmpc/next/configuration/theme

Enables or disables a backdrop behind modal dialogs to enhance visual clarity. Defaults to false.

```configuration
modal_backdrop: true | false
```

--------------------------------

### Style rmpc Progress Bar Elements

Source: https://mierak.github.io/rmpc/next/configuration/theme

Applies specific styles to different parts of the progress bar, including the track, elapsed portion, and the thumb.

```ron
progress_bar:
  track_style: "bold"
  elapsed_style: "green"
  thumb_style: "bold blue"
```

--------------------------------

### Set Maximum Album Art Size

Source: https://mierak.github.io/rmpc/next/configuration/album-art

This option sets a limit for the album art size in pixels. If the album art exceeds these dimensions, it will be resized. Setting it to (0, 0) removes the limit, allowing terminals that correctly report their size to determine it automatically. This is primarily for terminals that do not report their size accurately. The Ueberzug backend is unaffected by this setting.

```yaml
max_size_px: (<width>, <height>)
```

--------------------------------

### Enable Debug Logging (RUST_LOG)

Source: https://mierak.github.io/rmpc/next/guides/remote-commands

To view detailed error messages from remote commands, you can run rmpc with debug logging enabled by setting the `RUST_LOG` environment variable to `debug`. This helps in diagnosing issues when commands fail silently.

```shell
# Example: Run rmpc with debug logging
RUST_LOG=debug rmpc
```

--------------------------------

### Split Panes Horizontally with Borders

Source: https://mierak.github.io/rmpc/next/configuration/tabs

Configures a tab to split its content horizontally into two sub-panes, with borders applied.

```rmpc config
Split(
    direction = Horizontal,
    borders = ALL,
    panes = [
        Pane(size = '50%', pane = Queue),
        Pane(size = '50%', pane = AlbumArt)
    ]
)
```

--------------------------------

### Configure Tab Bar Styles

Source: https://mierak.github.io/rmpc/next/configuration/theme

Manages the appearance of the tab bar, including styles for the active and inactive tabs. The 'tab_bar.enabled' option is deprecated.

```configuration
tab_bar.active_style: <style>
tab_bar.inactive_style: <style>
```
Tokens:
Raw