Panes

Panes can be used either in your layout or in your tabs. They allow you to control what is displayed where and mix and match them to your liking.

Panes

Rmpc has several pane_types which can be displayed. These are:

Pane	Description
AlbumArt	The album art. Cannot be focused.
Cava	Displays a music visualiser using Cava. More info on its own page.
Queue	Table of the current song queue.
QueueHeader()	Header for the current queue, complimentary to the Queue pane
Directories	Browse music library by directory.
Browser()	A music library browser. Allows you to specify a root tag and an optional separator. Browser(root_tag: "<tag>", separator: ";"). Separator can be used to create multiple entries from one tag value, for example if a song has multiple genre values separated by ;.
Artists	Browse music library by artist tag. Is an alias for Browser pane with “artist” and “album” levels.
AlbumArtists	Browse music library by albumartist tag. Is an alias for Browser pane with “albumartist” and “album” levels.
Albums	Browse music library by album tag. Is an alias for Browser pane with just an “album” level.
Playlists	Browse saved playlists.
Sticker()	Browse songs ordered by an arbitrary MPD sticker. See the Sticker section for configuration options.
Search	Search music library.
Lyrics	Display synced lyrics.
ProgressBar	Displays the progress of the currently playing song.
Tabs	Displays a simple tab bar showing what tabs are available and which one is active.
Property	A special pane which can display a list of properties including styling, default values etc. Check the Example for more info.
Volume()	Interactive volume slider with mouse support. Supports Volume(kind: Slider(<config>)) configuration. More info in the Example
Empty()	An empty pane, a noop. Can be used as a spacer in your layout.

Property

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

The property pane, can be used to display one or more properties. The content of the pane can be aligned in case the pane’s size is bigger than its content. The content can also wrap scroll around in case it does not fit the pane’s size, this is controlled by the scroll_speed.

Example

Displays the currently elapsed time followed with a forward slash and the current song’s total duration. After that a Group is used to show song’s bitrate in the format (999 kbps), the group ensures that no parentheses will be shown if the bitrate cannot be determined. The text will also wrap scroll if the pane is not big enough for the content.

Pane(Property(
    content: [
        (kind: Property(Status(Elapsed))),
        (kind: Text(" / ")),
        (kind: Property(Status(Duration))),
        (kind: Group([
            (kind: Text(" (")),
            (kind: Property(Status(Bitrate))),
            (kind: Text(" kbps)")),
        ])),
    ],
    align: Right,
    scroll_speed: 1,
)),

Sticker

Sticker: Pane(Sticker(sticker: <string>, format: <property[]>?, limit: <number>?, sort: <sort>?))

A browser pane that lists songs ordered by an arbitrary MPD sticker. The pane uses the standard three-column browser layout and supports all common browser actions (add to queue, rate, show info, etc.).

A common use is a “recently played” view driven by the lastPlayed sticker (sticker: "lastPlayed", sort: ValueIntDesc).

Note

The sticker must be written by an external tool. For lastPlayed this can be an rmpcd plugin or an on_song_change hook. rmpc itself does not track play history.

Options

Option	Type	Default	Description
sticker	string	(required)	Name of the MPD sticker to read and order songs by.
format	property[]	browser_song_format from theme	Controls how each song is displayed. Uses the same property syntax as other browser panes.
limit	number or None	None (fetch all)	Maximum number of songs to show. None fetches every matching song.
sort	sort	Uri	Ordering of the results. One of Uri, UriDesc, Value, ValueDesc, ValueInt, ValueIntDesc.

The sort variants ending in Desc sort in descending order. Value sorts the sticker value lexicographically (as a string), while ValueInt sorts it numerically, ensure that the stickers only have numerical values when using ValueInt.

Example

// Minimal - show every song that has any `like` sticker value , inherit global browser_song_format
Pane(Sticker(sticker: "like"))

// "Recently played" — last 50 songs, newest first, with a custom format
Pane(Sticker(
    sticker: "lastPlayed",
    sort: ValueIntDesc,
    limit: Some(50),
    format: [
        (kind: Property(Artist), default: (kind: Text("Unknown Artist"))),
        (kind: Text(" - ")),
        (kind: Property(Title), default: (kind: Text("Unknown Title"))),
    ],
))

Browser

Browser: Pane(Browser(levels: BrowserLevel[]))

A custom browser pane with user defined nesting levels.

Each level defines one directory grouping in the browser. Each level groups the contained songs by one or more tags, can define sorting of the directories and what the directories will display. The levels can also be skipped if they contain only a single item.

Each grouping field is a list of tags that serve as fallback. For example, if you want to group songs by an albumartist tag but if some of the songs do not have it, you can define a fallback to artist. This would be group_by: [[AlbumArtist, Artist]]. These are a subset of properties, some properties like File are not available here.

The first level is special. Only the tags defined in group_by are available for sort_by and format. Fallback tags within group_by are not supported either.

Look at the following example and read the comments carefully to see what is possible:

Pane(Browser(
    levels: [
        (
            // Only tags defined in group_by are available on the first level. Fallback tags
            // are not supported here, each entry must have exactly one tag.
            // Multiple group_by entries produce one directory per unique combination of those
            // tags. sort_by and format must only reference tags defined in group_by.
            group_by: [[AlbumArtist], [Album], [Other("date")]],
            sort_by: [[AlbumArtist]],
            format: [
                (kind: Property(AlbumArtist), default: (kind: Text("<no artist>"))),
                (kind: Text(" - ")),
                (kind: Property(Album)),
                (kind: Text(" - ")),
                (kind: Property(Other("date")), default: (kind: Text("<no date>"))),
            ],
        ),
        (
            // Group all the songs in a given genre by "albumartist" or "artist" if albumartist is
            // not present. This will produce a list of all the artist that have some songs with the given genre.
            group_by: [[AlbumArtist, Artist]],
            // Sort by the same tags as the grouping.
            sort_by: [[AlbumArtist, Artist]],
            // Display the albumartist value, artist if it does not exist and "no artist" for
            // directory where all songs without either artist or albumartist will be grouped
            // It is highly recommended to only use properties that are in the "group_by". Otherwise
            // you might get some unexpected results since the values for the format are taken from
            // the first song in the group.
            format: [
                (kind: Property(AlbumArtist), default: (kind: Property(Artist), default: (kind: Text("no artist")))),
            ],
            // Possible values are "Single" and "SingleEmpty"
            // With "Single", if only one artist is in the directory, this level will be completely
            // skipped
            // With "SingleEmpty", if no artist is in the directory, meaning there would be only one
            // item named "no artist", this level will be completely skipped
            skip: SingleEmpty,
        ),
        (
            // Group songs for the artist by "album" and "date" with fallback to "originaldate"
            group_by: [[Album], [Other("date"), Other("originaldate")]],
            // Display "(1-1-1900) album name" as the format
            format: [
                (kind: Group([
                    (kind: Text("(")),
                    (kind: Property(Other("date"))),
                    (kind: Text(") ")),
                ])),
                (kind: Property(Album)),
            ],
            // On the last level, skip can have one more value: UnpackEmpty
            // If this directory would have albumA, albumB and songs without either album or date,
            // they will be unpacked directly into this level instead of its separate directory.
            skip: UnpackEmpty,
        ),
    ],
)),

Volume

Volume: Pane(Volume(kind: Slider(<config>) | VerticalSlider(<config>))

The Volume pane provides an interactive volume slider with mouse support. You can click to set volume directly or use scroll wheel to adjust volume in steps.

Currently, both the Slider and VerticalSlider kinds are supported.

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

Configure the appearance of the volume slider:

• symbols - An object with 5 one character long strings:

  • start - Symbol at the beginning of the slider (default: ”♪”)
  • filled - Symbol for the filled portion (default: ”─”)
  • thumb - Symbol for the current position indicator (default: ”●”)
  • track - Symbol for the empty portion (default: ”─”)
  • end - Symbol at the end of the slider (default: ”♫”)

• filled_style - Style for the filled portion of the slider (default: blue foreground)

• thumb_style - Style for the thumb/position indicator (default: blue foreground)

• track_style - Style for the empty portion of the slider (default: dark gray foreground)

Example

Volume(
    kind: Slider(
        symbols: (
            start: "♪",
            filled: "─",
            thumb: "●",
            track: "─",
            end: "♫",
        ),
        track_style: (fg: "gray"),
        filled_style: (fg: "green"),
        thumb_style: (fg: "white"),
    )
)

or

Volume(
    kind: VerticalSlider(
        symbols: (
            start: "♪",
            filled: "|",
            thumb: "●",
            track: "|",
            end: "♫",
        ),
        track_style: (fg: "gray"),
        filled_style: (fg: "green"),
        thumb_style: (fg: "white"),
    )
)

This creates a volume slider with speaker icons at the ends, using green for the filled portion and a white thumb with green background.

row

(left: <property>[], center: <property>[], right: <property>[])

Defines a single row in the header. Each row can have left, center and right configuration.

property

Describes a single segment (left, center or right) of the header. More info in the properties page.