1yambar-modules-script(5) File Formats Manual yambar-modules-script(5)
2
6 script - This module executes a user-provided script (or binary!)
7
9 This module executes a user-provided script (or binary!) that writes
10 tags on its stdout.
11 Scripts can be run in two modes: yambar polled, or continuously. In the
13 yambar polled mode, the script is expected to write one set of tags and
14 then exit. Yambar will execute the script again after a configurable
15 amount of time.
16 In continuous mode, the script is executed once. It will typically run
18 in a loop, sending an updated tag set whenever it needs, or wants to.
19 The last tag set is used (displayed) by yambar until a new tag set is
20 received. This mode is intended to be used by scripts that depends on
21 non-polling methods to update their state.
22 Tag sets, or transactions, are separated by an empty line (e.g. echo
24 ""). The empty line is required to commit (update) the tag even for
25 only one transaction.
26 Each tag is a single line on the format:
28 name|type|value
30 Where name is what you also use to refer to the tag in the yambar con‐
32 figuration, type is one of the tag types defined in yambar-tags(5), and
33 value is the tag’s value.
34 Example:
36 var1|string|hello
38 var2|int|13
39 <empty>
40 var1|string|world
41 var2|int|37
42 <empty>
43 The example above consists of two transactions. Each transaction has
45 two tags: one string tag and one integer tag. The second transaction
46 replaces the tags from the first transaction. Note that both transac‐
47 tions need to be terminated with an empty line.
48 Supported types are:
50 • string
52 • int
53 • bool
54 • float
55 • range:n-m (e.g. var|range:0-100|57)
56
59 User defined.
60
62 ┌──────────────┬─────────────────┬─────┬───────────────────────────────┐
63 │Name │ Type │ Req │ Description │
64 ├──────────────┼─────────────────┼─────┼───────────────────────────────┤
65 │path │ string │ yes │ Path to script/binary to exe‐ │
66 │ │ │ │ cute. Must either be an abso‐ │
67 │ │ │ │ lute path, or start with ~/. │
68 ├──────────────┼─────────────────┼─────┼───────────────────────────────┤
69 │args │ list of strings │ no │ Arguments to pass to the │
70 │ │ │ │ script/binary. │
71 ├──────────────┼─────────────────┼─────┼───────────────────────────────┤
72 │poll-interval │ integer │ no │ Number of milliseconds be‐ │
73 │ │ │ │ tween each script run. If un‐ │
74 │ │ │ │ set, or set to 0, continuous │
75 │ │ │ │ mode is used. │
76 └──────────────┴─────────────────┴─────┴───────────────────────────────┘
77
79 Here is an "hello world" example script:
80 #!/bin/sh
82 while true; do
84 echo "test|string|hello"
85 echo ""
86 sleep 3
87 echo "test|string|world"
89 echo ""
90 sleep 3
91 done
92 This script runs in continuous mode, and will emit a single string tag,
94 test, and alternate its value between hello and world every three sec‐
95 onds.
96 A corresponding yambar configuration could look like this:
98 bar:
100 left:
101 - script:
102 path: /path/to/script.sh
103 args: []
104 content: {string: {text: "{test}"}}
105 Another example use case of this module could be to display currently
107 playing song or other media from players that support MPRIS (Media
108 Player Remote Interfacing Specification):
109 bar:
111 center:
112 - script:
113 path: /usr/bin/playerctl
114 args:
115 - "--follow"
116 - "metadata"
117 - "-f"
118 - |
119 status|string|{{status}}
120 artist|string|{{artist}}
121 title|string|{{title}}
122 content:
123 map:
124 conditions:
125 status == Paused: {empty: {}}
126 status == Playing:
127 content: {string: {text: "{artist} - {title}"}}
128 The above snippet runs a playerctl utility in --follow mode, reacting
130 to media updates on DBUS and outputting status, artist and title of me‐
131 dia being played in a format that is recognized by yambar. See play‐
132 erctl documentation for more available metadata fields and control over
133 which players get used.
134
136 yambar-modules(5), yambar-particles(5), yambar-tags(5), yambar-decora‐
137 tions(5)
138 2023-07-22 yambar-modules-script(5)