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, Property or Group 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.

Group

kind: Group(<property>[])

A special kind of property that groups multiple properties together. If any of the properties in the group results in a None value, the whole group is considered None and the default value is used.

Property

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

Can display values from the 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.

Sticker

kind: Sticker("<sticker_key")

Can display stickers from the currently playing song, just like in the song table.

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(Status(Volume)) | Property(Status(RepeatV2)) | Property(Status(RandomV2)) | Property(Status(SingleV2)) | Property(Status(ConsumeV2)) | Property(Status(StateV2)) | Property(Status(Elapsed)) | Property(Status(Duration)) | Property(Status(Crossfade)) | Property(Status(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.

StateV2

kind: Property(Status(StateV2(playing_label: "<your label>", paused_label: "<your label>", stopped_label: "<your label>", playing_style: <style>, paused_style: <style>, stopped_style: <style>)))

The StateV2 property has additional configuration options. If you omit any of the values, the default is used, so you can for example do just: Status(StateV2(playing_label: "Playing"))orStatus(StateV2()). The default value is Status(StateV2(playing_label: "Playing", paused_label: "Paused", stopped_label: "Stopped")).

RepeatV2

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

Similar to StateV2. Allows you to configure labels for on/off states.

RandomV2

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

Similar to StateV2. Allows you to configure labels for on/off states.

ConsumeV2

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>)))

Similar to StateV2. Allows you to configure labels for on/off and one shot states. Note that oneshot state is available from MPD version 0.24.0, with earlier versions it get silently ignored.

SingleV2

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

Similar to StateV2. Allows you to configure labels for on/off and one shot states.

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"))
            ]
        )
    ],
),