sway-title-animator
Activity
Contributors
README
sway-title-animator
Animated Unicode titlebars for Sway. The Linux-only Go program talks directly
to the Sway/i3 IPC socket and adds an application label, optional presentation
indicator, and animated art to window titles. It is especially useful with
Sway's tabbed and stacked layouts.
Install
Build from native source with Entire's Git helper configured:
git clone entire://aws-eu-central-1.entire.io/et/marang/sway-title-animator
cd sway-title-animator
make install
This installs only sway-title-animator in ~/.local/bin. Release packages
depend only on Sway. Sound-reactive presets additionally use the optional
parec command (provided by libpulse on Arch and pulseaudio-utils on
Debian/Ubuntu; PipeWire users can use pipewire-pulse).
On Arch Linux, install the AUR package with:
yay -S sway-title-animator
Linux release downloads, including deb and rpm packages for amd64 and
arm64, are available from the
native download catalog.
See the release workflow for source, CI and publication
boundaries. Existing GitHub releases retain their historical identity.
With Go 1.26.10 or newer, install the standalone command from its owned module:
go install go.izoone.com/sway-title-animator/cmd/sway-title-animator@latest
This installs into $(go env GOPATH)/bin unless GOBIN is set. Owned module
versions start at v0.11.0; previous tags retain their original module path.
Go uses its normal public proxy and checksum database without custom settings.
Sway setup
Add this line to your Sway configuration, or include
contrib/sway/45-title-animator.conf:
exec_always --no-startup-id /usr/bin/sway-title-animator --replace --fps 25
For a source install, replace /usr/bin with $HOME/.local/bin. Apply later
configuration changes with swaymsg reload.
Presets and preview
List presets or preview every registered animation without a Sway connection:
sway-title-animator --list-presets
sway-title-animator --preview
The terminal preview puts each preset on a labeled line. Scroll with arrow
keys, Page Up/Page Down, or Home/End; press q or Ctrl-C to exit.
Select one preset with --preset NAME, or use SWAY_TAB_ANIMATION=NAME; the
configured rotation remains the default.
Each launch gets a fresh motion seed. A fixed seed remains deterministic for
tests. Sound variants use <base>_sound, preserve their base preset's motion,
fall back to that base when capture is unavailable, and are opt-in rather than
part of the default rotation. The sound-preset design record is in
docs/sound-presets-plan.md.
Configuration
Create a starting configuration with:
sway-title-animator --init-config
The default path is
$XDG_CONFIG_HOME/sway-title-animator/config.toml (or
~/.config/sway-title-animator/config.toml). See
config.example.toml for all settings, including frame
rate, rotation, glyphs, audio sensitivity, icons, and presentation glyphs.
The animator decodes the stable internal/titleindicator Sway-mark protocol
when another tool supplies it. It does not create session state, run a session
daemon, or require a session manager.
Moving to sway-session
Persistent work sessions now live in the separate
sway-session repository. The split
is planned for sway-title-animator v0.10.0 and the matching first
sway-session release.
For an upgrade from a release at or below v0.9.3, the old animator package owns
both sway-title-animator and sway-session; the new packages own one binary
each. Do not remove the old package separately. Either upgrade the animator
package first and install sway-session immediately afterward without
restarting Sway, or build/download both new packages and install the pair in
one pacman -U invocation. Do not use --overwrite. Then replace the old
session lines in your Sway config with the template and instructions from the
new sway-session package, while keeping the animator line above. Package
metadata must not use a blanket replaces relationship that can remove the
animator while installing the session package.
Development
Run the complete local/CI gate before handoff:
make verify
For animation changes, also inspect --preview at narrow and wide terminal
widths. Preserve exact requested output width, zero-width safety, fixed-seed
determinism, and the all-pairs visual-similarity guard.