Header

header: <row[]>

Configuration of the header. Header is displayed at the top of te window. It can display info about current song, the player state and custom widgets. It is an array of row objects. The number of these rows determines how many rows are going to be displayed in the header. If left empty, the header is not displayed at all. Each row can have left, center and right configuration to display various information about the player state and currently playing song.

row

(left: <header_property>, center: <header_property>, right: <header_property>)

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

header_property

Describes a single segment (left, center or right) of the header. This is a recursive data structure. Whenever a property is not present, the default fallback is used. This fallback can also have a default value.

kind

kind: <header_property_kind>

What property to display. Described in its own section

style

style: <style>

Style for the property.

default

default: <header_property>

This is a normal header property. It is used as a fallback value when the current property is not defined

header_property_kind

Kind can be one of two values, static Text or Property which can display song metadata, various player status info or predefined widgets.

Text

kind: Text("<string>")

Will display static text in the table. Mostly useful for default values. For example if a song is missing an album tag, “Unknown Album” can be displayed by specifying Text("Unknown Album") as the default.

Property

kind: Property(Song(...)) | Property(Status(...))) | Property(Widget(...)))

Can display values from currently playing song metadata, just like in the song table, info about the player status (volume, playing or stopped, current bitrate, …) or a predefined widget.

Property(Song)

kind: Property(Song(Filename)) | Property(Song(Title)) | Property(Song(Artist)) | Property(Song(Album)) | Property(Song(Duration)) | Property(Song(Other("<String>")))

This is similar to the SongProperty but is used for the header. It can display information about the song that is currently playing. The Other variant can be used to display any tag, even those not explicitly supported by rmpc.

Property(Status)

kind: Property(Song(Volume)) | Property(Song(Repeat)) | Property(Song(Random)) | Property(Song(Single)) | Property(Song(Consume)) | Property(Song(State)) | Property(Song(Elapsed)) | Property(Song(Duration)) | Property(Song(Crossfade)) | Property(Song(Bitrate))

These values display the current state of the player. For example, Volume will display the current volume, Repeat will display if the repeat mode is on or off, etc.

Property(Widget)

Property: Property(Widget(Volume)) | Property(Widget(States(active_style: <style>, separator_style: <style>)))

These are predefined “widgets” which you can use in your header. They differ from regular properties in that they can have additional styling options or display options.

Volume widget

kind: Property(Widget(Volume))

Shows volume with percentage and bars instead of just simple number. It looks something like this: Volume: ▁▂▃▄▅▆▇ 100%

States widget

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

Offers additional styling for active and inactive state. Looks like this: Repeat / Random / Consume / Single. Where the active states are highlighted with the active style and the inactive states are highlighted with the inactive style. The ’/’ is highlighted with the separator style.

Example

This configuration displays a header with single row. On the left side there is player state (Playing/Paused/Stopped) in yellow color inside brackets, ie. [Playing]. In the center there is the title of the currently playing song in bold. If there is no song playing, the text “No Song” is displayed. And on the right side there is the volume widget in blue color.

header: (
    rows: [
        (
            left: [
                (kind: Text("["), style: (fg: "yellow", modifiers: "Bold")),
                (kind: Property(Status(State)), style: (fg: "yellow", modifiers: "Bold")),
                (kind: Text("]"), style: (fg: "yellow", modifiers: "Bold"))
            ],
            center: [
                (kind: Property(Song(Title)), style: (modifiers: "Bold"),
                    default: (kind: Text("No Song"), style: (modifiers: "Bold"))
                )
            ],
            right: [
                (kind: Property(Widget(Volume)), style: (fg: "blue"))
            ]
        )
    ],
),