shelltrax
| Crates.io | shelltrax |
| lib.rs | shelltrax |
| version | 20251214.0.2 |
| created_at | 2025-12-14 23:51:13.42396+00 |
| updated_at | 2025-12-14 23:51:13.42396+00 |
| description | A cmus-inspired terminal music player with Last.fm scrobbling |
| homepage | https://github.com/ducks/shelltrax |
| repository | https://github.com/ducks/shelltrax |
| max_upload_size | |
| id | 1985290 |
| size | 2,228,098 |
(ducks)
documentation
README
TUI Music Player (Rust)
A terminal-based music player written in Rust using ratatui and crossterm.
Navigate your filesystem, browse audio files, and play music -- all in the terminal.
Features
- TUI interface with multiple screens
- Library view with artist/album hierarchy
- File browser
- Playlist (coming soon)
- Navigate directories using keyboard
- Dotfiles are hidden by default
- Modular, extensible codebase
- Persistent library with smart metadata handling
- Directory-based album grouping (prevents album splitting)
- Filename fallbacks for missing ID3 tags
- Automatic track number extraction from filenames
- Filters out macOS metadata files (_MACOSX, . files)
- ZIP import: Extract and import albums directly from zip files
- Search functionality: Quick jump to artists, albums, or tracks
- Delete from library: Remove entries without touching actual files
- Playback controls with autoplay and repeat modes
Screenshots
Library Screenshot 1
Library Screenshot 2
Browser Screenshot 1
Installation
git clone git@github.com:ducks/shelltrax.git
cd shelltrax
cargo run
Configuration
Theming
Shelltrax supports custom color themes via a TOML configuration file.
- Copy the example theme file:
mkdir -p ~/.config/shelltrax
cp theme.toml.example ~/.config/shelltrax/theme.toml
- Edit
~/.config/shelltrax/theme.tomlto customize colors
The theme supports:
- Named colors (e.g.,
red,green,cyan) - Hex colors (e.g.,
#b16286) - See
theme.toml.examplefor all available options and examples
Keybindings
Shelltrax supports both arrow keys and vim-style navigation.
Global
| Key | Action |
|---|---|
q |
Quit |
1 |
Go to Library |
5 |
Go to Browser |
/ |
Enter search mode |
Esc |
Exit search mode |
Navigation
| Key | Action |
|---|---|
j / Down |
Move down |
k / Up |
Move up |
h |
Move left (context-dependent) |
l |
Move right (context-dependent) |
g |
Go to top |
G |
Go to bottom |
Browser View
| Key | Action |
|---|---|
a |
Add file/dir to library |
x |
Extract and import zip file |
Backspace |
Go up a directory |
Enter |
Open directory |
Library View
| Key | Action |
|---|---|
Tab |
Toggle focus left/right |
Enter |
Play selected track |
Space |
Toggle artist/album expanded |
d |
Delete from library (files safe) |
c |
Toggle pause/resume |
b |
Next track |
z |
Previous track |
p |
Toggle autoplay |
r |
Cycle repeat mode (Off/All/Track) |
Planned Features / TODO
- Hide dotfiles
- Prevent duplication
- Library persistence
- Audio playback via
cpal - Autoplay
- Footer bar with now playing info and progress
- Search functionality (jump to artists/albums/tracks)
- Delete from library (without touching files)
- ZIP import and extraction
- Directory-based album grouping
- Filename fallbacks for metadata
- Repeat modes (Off/All/Track)
- Sort directories before files
- Playlist screen with queue
- Config file for keybindings and paths
- Save/restore last visited directory
- Match more
cmuskeybindings and behaviors (e.g.v,:) - Gapless playback
- Audio visualizer