Configuring

Overview

Fum's configuration is located in $HOME/.config/fum/config.jsonc This file defines the layout and behavior of widgets in your Fum application. The configuration is structured in jsonc format. Basically a normal json with comment support. Example config:

{
  "players": ["spotify", "lollypop", "org.mpris.MediaPlayer2.mpv"],
  "use_active_player": false,
  "fps": 10,
  "keybinds": {
    "esc;q": "quit()",
    "h": "prev()",
    "l": "next()",
    " ": "play_pause()"
  },
  "align": "center",
  "direction": "vertical",
  "flex": "start",
  "width": 20,
  "height": 18,
  "border": false,
  "padding": [0, 0],
  "bg": "reset",
  "fg": "reset",
  "cover_art_ascii": "~/.config/fum/ascii.txt",
  "layout": []
}  

Properties

players (Optional)

List of player names that will be detected by fum. This can be the name or the bus_name of the player. Note that identity is case insensitive and bus_name are not.

use_active_player (Optional)

Whether to use the most likely active player when there it can't find players on the players array.

keybinds (Optional)

See Keybinds.

align (Optional)

Where in the terminal fum will be positioned in.

Values:

• left
• top
• right
• bottom
• center
• top-left
• top-right
• bottom-left
• bottom-right

Default: center

direction (Optional)

See #Direction.

flex (Optional)

See #ContainerFlex.

width / height (Optional)

The main width & height of fum.

bg / height (Optional)

See Bg & Fg.

border (Optional)

Whether to draw a border around the widget.

padding (Optional)

Padding on fum main container.

• Default: false

cover_art_ascii (Optional)

The path pointing into an ascii file. This ascii art will be displayed on cover art area when there is no music playing.

layout (Optional)

List of widgets.

Widgets

Container

A container widget that organizes child widgets in a specific direction and layout.

• Fields:
  • width: u16 (Optional). Specifies the width of the container. See #Width & Height.
  • height: u16 (Optional). Specifies the height of the container. See #Width & Height.
  • border: boolean (Optional). Whether to draw a border around the widget. Default: false
  • padding: [u16, u16] (Optional). Whether to add padding on the container. Default: [0, 0]
  • direction: Direction (Optional). Specifies the layout direction of child widgets. See #Direction.
  • flex: ContainerFlex (Optional). Specifies how space is distributed among child widgets. See #ContainerFlex.
  • bg: The background color of this container area. See Bg & Fg.
  • fg: The foreground color of the children. See Bg & Fg.
  • children: Widgets[] (Required). The childrens of the container.

Example:

{
  "type": "container",
  "width": 20,
  "height": 20,
  "border": false,
  "padding": [0, 0],
  "direction": "vertical",
  "flex": "start",
  "bg": "blue",
  "fg": "black",
  "children": [
    {
      "type": "empty",
      "size": 1
    }
  ]
}

CoverArt

Displays music cover art.

• Fields:
  • width: u16 (Optional). Specifies the width of the cover art. See #Width & Height.
  • height: u16 (Optional). Specifies the height of the cover art. See #Width & Height.
  • border: boolean (Optional). Whether to draw a border around the widget. Default: false
  • resize: CoverArtResize (Optional). Specifies which resize method to use.
    • Values:
      • fit - If the width or height is smaller than the area, the image will be resized maintaining proportions.
      • crop - If the width or height is smaller than the area, the image will be cropped.
      • scale - Scale the image.
    • Default: scale
  • bg: The background color of the cover_art. See Bg & Fg.
  • fg: The foreground color of the cover_art (Does really nothing on this widget). See Bg & Fg.

Example:

{
  "type": "cover-art",
  "width": 20,
  "height": 20,
  "border": false,
  "resize": "scale",
  "bg": "red",
  "fg": "#000000"
}

Label

Displays a text label.

• Fields:
  • text: Text (Required). The text to display in the label. See #Text.
  • align: LabelAlignment (Optional). Specifies the alignment of the text. See #LabelAlignment.
  • truncate: boolean (Optional). Specifies whether to truncate the text if it exceeds the available space.
    • Default: true
  • bold: boolean (Optional). Makes the label text bold.
    • Default: false
  • bg: The background color of the label. See Bg & Fg.
  • fg: The foreground color of the label. See Bg & Fg.

Example:

{
  "type": "label",
  "text": "$title",
  "align": "center",
  "truncate": true,
  "bold": false,
  "bg": "black",
  "fg": "white"
}

Button

• Fields:
  • text: Text (Required). The text to display in the button. See #Text.
  • id: String (Optional). A unique identifier for the button, This is used for identifying where the button is in the terminal and if its been clicked. (Automatically generated if not provided.)
  • action: String (Optional). Specifies an action to perform when the button is clicked. See #Functions.
  • exec: String (Optional). Spawns a shell command to execute when the button is clicked (Note that this will quietly execute and will not notify you if it errors).
  • bold: boolean (Optional). Makes the label text bold.
    • Default: false
  • bg: The background color of the button. See Bg & Fg.
  • fg: The foreground color of the button text. See Bg & Fg.

Example:

{
  "type": "button",
  "text": "$status_icon",
  "action": "play_pause()",
  "exec": "echo hi",
  "bold": false,
  "bg": "reset",
  "fg": "magenta"
}

Progress

Displays a progress bar.

• Fields:
  • size: u16 (Optional). specifies the size (width) of the progress bar. See #Width & Height.
  • direction: Direction (Optional). whether to display the progress bar horizontally / vertically. See #Direction.
  • progress: ProgressOption (Required).
    • char: The character used to represent the progress portion of the progress bar.
    • bg: The background color of the progress. See Bg & Fg.
    • fg: The foreground color of the progress. See Bg & Fg.
  • empty: ProgressOption (Required).
    • char: The character used to represent the empty portion of the progress bar.
    • bg: The background color of the empty. See Bg & Fg.
    • fg: The foreground color of the empty. See Bg & Fg.

Example:

{
  "type": "progress",
  "size": 10,
  "direction": "horizontal"
  "progress": {
    "char": "",
     "fg": "red",
     "bg": "blue"
  },
  "empty": {
    "char": "-",
     "fg": "blue",
     "bg": "red"
  }
}

Volume

Similar to #Progress Widget but for Volume.

• Fields:
  • size: u16 (Optional). specifies the size (width) of the progress bar. See #Width & Height.
  • direction: Direction (Optional). whether to display the volume bar horizontally / vertically. See #Direction.
  • volume: VolumeOption (Required).
    • char: The character used to represent the volume portion of the progress bar.
    • bg: The background color of the progress. See Bg & Fg.
    • fg: The foreground color of the progress. See Bg & Fg.
  • empty: VolumeOption (Required).
    • char: The character used to represent the empty portion of the progress bar.
    • bg: The background color of the empty. See Bg & Fg.
    • fg: The foreground color of the empty. See Bg & Fg.

Example:

{
  "type": "volume",
  "size": 10,
  "direction": "vertical",
  "volume": {
    "char": "/",
     "fg": "red",
     "bg": "blue"
  },
  "empty": {
    "char": " ",
     "fg": "blue",
     "bg": "red"
  }
}

Empty

Represents an empty space.

• Fields:
  • size: u16 (Required). Specifies the size of the empty space.

Example:

{
  "type": "empty",
  "size": 1
}

Widget Properties

Width & Height

width and height are often optional properties. When not defined, the widget will automatically fill the remaining available space.

Direction

This property specifies the layout direction of the component.

• Values:
  • horizontal
  • vertical
• Default: horizontal

LabelAlignment

Specifies the alignment of text within a label.

• Values:
  • left
  • center
  • right
• Default: left

ContainerFlex

Defines how space is distributed among items in a container.

• Values:
  • start
  • center
  • end
  • space-around
  • space-between
• Default: start

Bg & Fg

• Variants:
  • reset - The default color.
  • black
  • white
  • green / lightgreen
  • yellow / lightyellow
  • blue / lightblue
  • red / lightred
  • magenta / lightmagenta
  • cyan / lightcyan
  • gray / darkgray
  • rgb - An RGB color. Example: "fg": {"Rgb": [255, 0, 255]}
  • indexed - An 8-bit 256 color. Example {"fg": {"Indexed":10}}
• Default both bg, fg: reset

Text

Available variables:

• $title - Title of the music.
• $artists - Artists of the music.
• $album - Album name of the music.
• $status-icon - A single ascii icon that represents the status / playback state.
• $status-text - Similar to $status-icon but in text format instead of nerdfonts icon.
• $position - The current position / progress of the music.
• $position-ext - Same as $position but prepended 0 at the start.
• $length - The total length of the music.
• $length-ext - Same as $length but prepended 0 at the start.
• $remaining-length - The remaining length of the music.
• $remaining-length-ext - Same as $remaining-length but prepended 0 at the start.
• $volume - The current player volume (0 - 100).

Text functions:

• get_meta(key: string) - Get a specific metadata that is not available in the variables above.
• var($foo, $length) - Define a mutable variable, where $foo is the variable name & $length is the variable value. You can use toggle() & set() actions to mutate it. See #Actions. For those actions.

Actions

Available actions:

• quit() - Quits fum.
• stop() - Stops the player.
• play() - Play the music.
• pause() - Pause the music.
• prev() - Back the music.
• play_pause() - Play / Pause the music.
• next() - Skips the music.
• shuffle_off() - Turn off the shuffle.
• shuffle_toggle() - Toggles the shuffle on / off.
• shuffle_on() - Turn on the shuffle.
• loop_none() - Set the loop to none.
• loop_playlist() - Set the loop to playlist.
• loop_track() - Set the loop to track.
• loop_cycle() - Cycle loop: none -> playlist -> track -> none.
• forward(2500) - Fast forward the music 2500 milliseconds.
• backward(2500) - Step backward the music 2500 milliseconds.
• forward(-1) - If -1 used in forward(-1) it will go to the end of the track.
• backward(-1) - If -1 used in backward(-1) it will go to the start of the track.
• volume(+10) - Increases the volume +10.
• volume(-10) - Decreases the volume -10.
• volume(50) - Sets the volume to 50 (0 - 100).
• toggle($foo, $length, $remaining-length) - Toggles the value of a variable, where $foo is the name and $length, $remaining-length is the values that will be toggled.
• set($foo, $title) - Set the value of a variable, where $foo is the name and $title is the value to set.

Debugging

The preferred way to debug widgets / areas is by using the bg property. You could set a specific container or a widget background color to see their bounding area.

Example full config:

{
  "players": ["spotify", "lollypop", "org.mpris.MediaPlayer2.mpv"],
  "use_active_player": false,
  "debug": false,
  "width": 20,
  "height": 18,
  "layout": [
    { "type": "cover-art" },
    {
      "type": "container",
      "direction": "vertical",
      "children": [
        { "type": "label", "text": "$title", "align": "center" },
        { "type": "label", "text": "$artists", "align": "center" },
        { "type": "empty", "size": 1 },
        {
          "type": "container",
          "height": 1,
          "flex": "space-around",
          "children": [
            { "type": "button", "text": "󰒮", "action": "prev()" },
            { "type": "button", "text": "$status-icon", "action": "play_pause()" },
            { "type": "button", "text": "󰒭", "action": "next()" }
          ]
        },
        { "type": "empty", "size": 1 },
        { "type": "progress", "progress": { "char": "󰝤" }, "empty": { "char": "󰁱" } },
        {
          "type": "container",
          "height": 1,
          "flex": "space-between",
          "children": [
            { "type": "label", "text": "$position", "align": "left" },
            { "type": "label", "text": "$length", "align": "right" }
          ]
        }
      ]
    }
  ]
}