yambar-modules-script - Man Page

This module executes a user-provided script (or binary!) that writes tags on its stdout.

Scripts can be run in two modes: yambar polled, or continuously. In the yambar polled mode, the script is expected to write one set of tags and then exit. Yambar will execute the script again after a configurable amount of time.

In continuous mode, the script is executed once. It will typically run in a loop, sending an updated tag set whenever it needs, or wants to. The last tag set is used (displayed) by yambar until a new tag set is received. This mode is intended to be used by scripts that depends on non-polling methods to update their state.

Tag sets, or transactions, are separated by an empty line (e.g. echo ""). The empty line is required to commit (update) the tag even for only one transaction.

Each tag is a single line on the format:

  name|type|value

Where name is what you also use to refer to the tag in the yambar configuration, type is one of the tag types defined in yambar-tags(5), and value is the tag’s value.

Example:

  var1|string|hello
  var2|int|13
    <empty>
  var1|string|world
  var2|int|37
    <empty>

The example above consists of two transactions. Each transaction has two tags: one string tag and one integer tag. The second transaction replaces the tags from the first transaction. Note that both transactions need to be terminated with an empty line.

Supported types are:

• string
• int
• bool
• float
• range:n-m (e.g. var|range:0-100|57)

User defined.

Here is an "hello world" example script:

  #!/bin/sh

while true; do
    echo "test|string|hello"
    echo ""
    sleep 3

    echo "test|string|world"
    echo ""
    sleep 3
done

This script runs in continuous mode, and will emit a single string tag, test, and alternate its value between hello and world every three seconds.

A corresponding yambar configuration could look like this:

  bar:
    left:
      - script:
          path: /path/to/script.sh
          args: []
          content: {string: {text: "{test}"}}

Another example use case of this module could be to display currently playing song or other media from players that support MPRIS (Media Player Remote Interfacing Specification):

  bar:
    center:
      - script:
          path: /usr/bin/playerctl
          args:
            - "--follow"
            - "metadata"
            - "-f"
            - |
              status|string|{{status}}
              artist|string|{{artist}}
              title|string|{{title}}
          content:
            map:
              conditions:
                status == Paused: {empty: {}}
                status == Playing:
                  content: {string: {text: "{artist} - {title}"}}

The above snippet runs a playerctl utility in --follow mode, reacting to media updates on DBUS and outputting status, artist and title of media being played in a format that is recognized by yambar. See playerctl documentation for more available metadata fields and control over which players get used.

yambar-modules(5), yambar-particles(5), yambar-tags(5), yambar-decorations(5)

yambar-modules(5).