# 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.
[](https://crates.io/crates/ceol)
[](https://docs.rs/ceol)
[](https://github.com/Tknott95/KnottMusic/blob/main/LICENSE)
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:
```sh
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:
```sh
cargo install ceol --locked
ceol
```
Point Ceol at any mix of files and folders:
```sh
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
```sh
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:
```sh
./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](https://github.com/Tknott95/KnottMusic/blob/main/docs/UX_BEAUTY_GATE.md).
## Keyboard shortcuts
| `Space` | Play or pause |
| `Ctrl+O` | Add music files |
| `Ctrl+Shift+O` | Add music folders recursively |
| `Ctrl+Right` / `Ctrl+Left` | Next / previous track |
| `Ctrl+M` | Toggle compact widget mode |
| `Ctrl+S` | Toggle shuffle |
| `Left` / `Right` | Seek backward / forward 10 seconds |
| `Up` / `Down` | Raise / lower volume |
| `M` | Mute or unmute |
| `R` | Cycle repeat off / all / one |
| `B` or `Ctrl+B` | Save or remove a point at the current time |
| `[` / `]` | Jump to the previous / next saved point |
| `Alt+Up` / `Alt+Down` | Reorder the selected track |
| `Delete` | Remove the selected track |
| `Ctrl+Delete` | Clear the queue |
## 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+):
```sh
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
```sh
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](https://github.com/Tknott95/KnottMusic/blob/main/LICENSE).
Product direction and design are by Knott Dynamics; created by Trevor Knott.