Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

When widgets update

Atsurae redraws a widget only when something it shows has changed. Knowing what triggers an update helps you build widgets that are both up to date and cheap to run.

Atsurae looks at the tokens in your elements and starts only the data sources they need. If no enabled widget uses {track}, Atsurae doesn’t listen for music at all.

Source Tokens Refreshes
Clock dates, times, *.progress Exactly on each new minute, or each second if a widget shows seconds
Battery {battery}, {batteryState}, {battery.level} Whenever macOS reports a change
CPU and memory {cpu}, {memory}, *.level Every 5 seconds
Now playing {track}, {artist}, {lastTrack}, {lastArtist} Whenever Music or Spotify changes track or pauses
Weather {weather.*} Every 30 minutes
Script {script.*} See below

The clock switches to once a second only while an enabled widget actually shows seconds ({second}, {time} with Show seconds on, or a {date:…} pattern containing s).

When a source changes, Atsurae works out each element’s new text or value and redraws only the elements whose content changed. If your clock shows {hour}:{minute}, it redraws once a minute; the date beneath it redraws once a day.

A script’s update(context) runs:

  1. When the widget appears: it’s turned on, Atsurae starts, or the widget’s files change
  2. On its schedule, set by updateEvery:
    • "minute" (the default): just after each new minute
    • "second": every second
    • a number: every that many seconds, e.g. 300 for every five minutes (at least 1)
  3. When the battery, the playing song or the weather changes, so scripts can react to them right away

A script doesn’t run every time the CPU or memory figures refresh. Those are read on the script’s own schedule.

Choose the slowest schedule that looks right. A countdown in days only needs "minute", or even 3600. A seconds counter needs "second".

To save energy, Atsurae pauses all data sources and scripts:

  • while the displays are asleep
  • while no widget is turned on (there’s no widget window at all then)
  • when Atsurae’s wallpaper is turned off, e.g. after signing out

When the displays wake, everything refreshes at once, so widgets are correct immediately.

While the Library or Customize Widgets is open, Atsurae runs the scripts of every widget, even ones that are turned off, so their previews are live. Previews also fill in example values for data that’s missing, like “Song Title” when nothing is playing, so you can see the whole layout. Those example values never appear on the desktop.

Atsurae watches your widgets folder. When you save a file:

  1. The widget’s files are read and checked again (within about 0.3 seconds).
  2. Its fonts and images are reloaded.
  3. Its script starts fresh: global variables are reset, and update runs right away.
  4. The desktop and every preview redraw.