cantus

A beautiful interactive music widget for Wayland

Features

Graphics: Powered by wgpu for high-performance, animated rendering of the music widget.

Queue Display: Displays your spotify queue in a visual timeline, shows upcoming songs as well as the history.

Playback Controls: Provides playback controls for play/pause, skip forward/backward by clicking to seek to a song, and volume adjustment with scroll. You can also smoothly drag the whole bar to seek through the timeline.

Playlist Editing: Favourite playlists to be displayed, shows when a song is contained in that playlist and allows you to add/remove songs from the playlist. (Also includes star ratings!)

Cantus.Preview.mp4

Usage

cantus can be run in two different modes: Wayland native (using layer-shell protocol) or as a standard window using winit.

Getting a Spotify API key

Due to Spotify's rate limiting, you will need to get an API key from https://developer.spotify.com/dashboard/applications and add it to the config file under the spotify_client_id key.

Installing with Nix

Available in nixpkgs.

As a flake for home manager: Add to flake.nix inputs cantus.url = "github:CodedNil/cantus"; Enable it as a systemd module with home-manager:

imports = [ inputs.cantus.homeManagerModules.default ];
programs.cantus = {
  enable = true;
  package = pkgs.cantus;
  settings = {
    monitor = "eDP-1";
    tempestas_enabled = true;
    location = [ 51.5 (-0.1) ];
    status_enabled = true;
    height = 40.0;
    timeline_future_minutes = 12.0;
    timeline_past_minutes = 1.5;
    history_width = 100.0;
    playlists = [ "Rock & Roll" "Instrumental" "Pop" ];
    ratings_enabled = true;
  };
};

Building from Source

To build Cantus from source, ensure the following dependencies are installed:

• Rust (with cargo)
• wayland-protocols
• clang
• libxkbcommon
• wayland
• vulkan-loader
• PipeWire and WirePlumber command-line tools (pw-record and wpctl)

Then, from the root of the repository, run:

cargo build --release

The application builds with stable Rust and embeds the checked-in Rust-GPU shader. Shader regeneration is a separate developer operation using nightly Rust; release and downstream package builds do not require it. Isthmus rejects stale shader artifacts during ordinary builds. Rebuild after changing shader code with:

just shader

To install it system-wide

sudo cp target/release/cantus /usr/bin