melors

Keyboard-first terminal MP3 player written in Rust.

Highlights

• Local-only MP3 library scanning
• Fast keyboard workflow (no mouse)
• Search + playlists + now playing + visualizer layout
• Persistent playback state and queue
• Theme presets and visualizer modes
• Tag editing (title/artist/album) from TUI

Quick Start

git clone https://github.com/TrVHau/melors
cd melors
cargo run --release

Install

After the crate is published on crates.io:

cargo install melors
melors

Install directly from GitHub:

cargo install --git https://github.com/TrVHau/melors melors
melors

Linux build prerequisite (for audio backend):

sudo apt-get install -y pkg-config libasound2-dev

If your distro is not Debian/Ubuntu (for example Defora), install equivalent ALSA development packages using your system package manager.

Runtime Paths

Created automatically on first run:

• Config: ~/.config/melors/config.toml
• Database: ~/.local/share/melors/db.sqlite
• Cache: ~/.cache/melors/
• Default music dir: ~/Music/melors/

Drop .mp3 files in your music dir and press r to rescan anytime.

Configuration

~/.config/melors/config.toml

music_dir = "/home/you/Music/melors"

Keybindings

App and Navigation

• q: quit
• Up / Down: move selection
• Enter: play selected track

Playback

• Space: play/pause
• n: next track
• p: previous track
• Left / Right: seek -5s / +5s
• Shift+Left / Shift+Right: seek -10s / +10s
• [ / ]: volume down/up

Library

• s: search mode
• r: rescan music directory
• f: toggle favorite on selected track
• a: open playlist picker to add selected (or currently playing) track

Metadata Editing

• t: edit selected track metadata (title/artist/album). Saving will also rename filename using Artist - Title (or Title when artist is empty).

Tag editor:

• Tab: next field
• Enter: save
• Esc: cancel

Playlist Quick Flow

1. Press l to open playlist mode. Playlist appears inline in the left pane, replacing Library while keeping Now Playing and Visualizer visible. On narrow terminals, playlist view auto-switches to stacked mode for better readability.
2. Use Up/Down to choose playlist or item.
3. Press Enter on a playlist to open it; press Enter on + New playlist to name it first, then press Enter again to create it.
4. Press a in Library to open playlist picker, then Enter on a playlist to add the track. If you choose + New playlist, melors asks for the playlist name first.
5. Press d in items view to remove the selected track from that playlist.
6. Press r in playlists view to rename the selected playlist, then Enter to save.
7. Press x in playlists view to open a delete confirmation, then Enter or x again to confirm.
8. Press Esc in items view to go back to playlists; press Esc again to close.
9. Press Enter in items view to play.
10. Once a playlist is opened for playback, it becomes the current Up Next list in the main UI.

Playback Modes and Visualizer

• Alt+0: visualizer Off (low-power mode)
• e: cycle repeat (Off -> One -> All)
• u: toggle shuffle
• Alt+1: visualizer Demo Bars (lightweight example)
• Alt+2: visualizer Clock
• Alt+3: visualizer CMatrix
• Alt+T: cycle UI theme (Neon -> Forest -> Ocean -> Rose -> Cyber -> Lava -> Aurora -> Candy -> Prism -> Scanline)

Project Structure

src/
	app/
		actions/
			boot.rs
			playback.rs
			queue.rs
			library.rs
			rename.rs
			session.rs
		mod.rs
		state.rs
	core/
		config/
			mod.rs
			load.rs
			paths.rs
		model.rs
	features/
		player/
			mod.rs
			control.rs
			analysis.rs
		search.rs
	services/
		scanner/
			mod.rs
			io.rs
			validate.rs
			watcher.rs
		storage/
			mod.rs
			migrations.rs
			tracks.rs
			playback.rs
			queue.rs
		metadata.rs
	ui/
		input/
			dispatch.rs
			normal.rs
			modes.rs
			selection.rs
		render/
			chrome.rs
			lists.rs
			playback.rs
			visualizer.rs
			theme.rs
		state/
			model.rs
			mode.rs
			cache.rs

Development

cargo check
cargo run
cargo package
cargo publish --dry-run

Notes

• Visualizer Alt+1 is currently a deterministic demo-bars mode, not FFT-driven spectrum analysis.

• Playlist items support play and remove; adding always starts from Library with a.

• artifacts/release/checksums-<candidate-id>.txt

• artifacts/release/release-summary-<candidate-id>.md

• artifacts/release/approval-events.log

Release gate inputs:

• config/release-policy.toml
• config/docs-sync-checklist.md
• Release notes reference path (RELEASE_NOTES_PATH, defaults to docs/README.md)

License

MIT. See LICENSE.