Ceol

Ceol is a polished, local-first music player for Linux by Knott Dynamics and Trevor Knott. It combines a complete GTK desktop player with a purpose-built compact widget, backed by GStreamer for dependable local playback.

Ceol has no account, telemetry, advertising, or network service. Your music paths and playback state stay on your machine.

Highlights

• Add individual tracks, recursively import one or more folders, or drop either directly onto the window
• Launch against a library or selection with ceol ~/Music album.flac
• Reorder, remove, and clear a durable local playback queue
• Play, pause, seek, skip, mute, and adjust volume from either layout
• Repeat off/all/one and no-repeat shuffle cycles with real back/forward history
• Embedded cover art plus title, artist, album, codec, and bitrate metadata
• Exact-track and position resume, resilient when earlier files disappear
• Persistent, track-specific saved points with previous/next wraparound
• Audio-reactive 56-band spectrum display and animated signal view
• A dedicated compact widget that preserves artwork, timeline, playback state, eight transport controls, and one-step expansion
• Keyboard-first operation, native drag-and-drop, and desktop Open With integration
• MP3, FLAC, Ogg, Opus, WAV, M4A, and AAC through installed GStreamer plugins

Install from crates.io

Ceol needs GTK 4, GStreamer, and the GStreamer plugins for the formats you use. On Ubuntu or Debian, install them first:

sudo apt install libgtk-4-dev libgstreamer1.0-dev \
  gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
  gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly

Then install and launch the native player:

cargo install ceol --locked
ceol

Point Ceol at any mix of files and folders:

ceol ~/Music ~/Downloads/new-album track.flac

Folders are scanned recursively in a stable, case-insensitive name order. Unreadable locations and unsupported files are skipped safely.

Build from source

git clone https://github.com/Tknott95/KnottMusic.git
cd KnottMusic
cargo run --release -- ~/Music

For a user-local release build, app-menu launcher, and scalable icon:

./scripts/install.sh

The binary goes to $XDG_BIN_HOME, or $HOME/.local/bin by default. Remove those installed desktop files with ./scripts/uninstall.sh.

Compact widget

Compact mode is a real alternate surface, not a squeezed desktop window. It keeps the active artwork, title and metadata, elapsed and total time, direct seeking, shuffle, repeat, ±10-second seek, previous/next, play/pause, mute, and live status. Its bookmark menu can save the current timestamp and flip through saved points without expanding. Press Ctrl+M or select Widget; the Expand action always returns to the full queue and visualizer.

The release gate compares the full and compact surfaces alongside established GNOME adaptive-layout guidance and Apple Music's MiniPlayer pattern in the UX beauty gate.

Keyboard shortcuts

Local data and package boundary

At runtime, Ceol writes only its resumable playback session—including saved points—beneath $XDG_STATE_HOME/ceol/session.json (normally ~/.local/state/ceol/session.json). Delete that file to reset the queue and playback state.

The crates.io artifact uses an explicit allowlist. It contains the Rust source, native artwork, desktop integration, installer scripts, documentation, license, and Cargo manifests only. It excludes runtime sessions, logs, target/, web dependencies, local caches, and generated Studio builds.

Repository workspace

The repository also contains KnottMusic Studio, a browser-based local composer with a seeded generator, pattern editor, mixer, arrangement controls, audio-reactive Three.js view, autosave, and WAV/MIDI/project export. The Studio is developed with Node.js 20.19+ (or 22.12+):

npm install
npm run dev

Run npm test for its focused tests and npm run build for a production build. The Studio is intentionally not bundled in the ceol Cargo package.

Development checks

cargo fmt --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings
cargo doc --locked --no-deps
cargo package --locked

Ceol is released under the MIT License. Product direction and design are by Knott Dynamics; created by Trevor Knott.