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.

1. Copy the example theme file:

mkdir -p ~/.config/shelltrax
cp theme.toml.example ~/.config/shelltrax/theme.toml

2. Edit ~/.config/shelltrax/theme.toml to customize colors

The theme supports:

• Named colors (e.g., red, green, cyan)
• Hex colors (e.g., #b16286)
• See theme.toml.example for 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 cmus keybindings and behaviors (e.g. v, :)
• Gapless playback
• Audio visualizer