yambar-modules-script(5)

✨ NAME ✨

okay so bestie, this is yambar-modules-script(5), from the File Formats Manual — the manual for script, aka the module that executes a user-provided script (or binary!) and reads tags from its stdout. 💖

🦋 DESCRIPTION 🦋

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

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 depend 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. Yes, even for just one transaction — commit that thing, bestie.

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 <empty> marker is where the actual empty line goes — like your echo "" moment.

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. Both. Not one. Both.

Supported types are:

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

🎀 TAGS 🎀

User defined. 💅 You make the tags, you name the tags, you live your truth.

👑 CONFIGURATION 👑

Here’s the config tea, bestie — every key, its type, whether it’s required, and what it does:

• path — type: string; required: yes. Path to script/binary to execute. Must either be an absolute path, or start with ~/..
• args — type: list of strings; required: no. Arguments to pass to the script/binary.
• poll-interval — type: integer; required: no. Number of milliseconds between each script run. If unset, or set to 0, continuous mode is used.

🌈 EXAMPLES 🌈

Here is a "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.

💜 SEE ALSO 💜

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

---

okay bye bestie 🫶 this page is yambar-modules-script(5), dated 2024-04-22. slay and happy tagging. ✨