A minimalist terminal-based MP3 music player built with Rust.

• Beautiful TUI: Clean terminal interface with cyberpunk green theme
• High-Quality Playback: MP3 audio support with crystal-clear sound
• Visual Progress: Real-time progress bar with time display
• Smart Controls: Intuitive keyboard controls with popup help
• Smooth Seeking: Instant seek without playback interruption
• Playback Modes: Normal sequential and random shuffle
• Keyboard-Driven: Lightning-fast keyboard-only interface
• Fuzzy Search: Real-time search with / key - find songs instantly
• Vim-Style Navigation: Full vim keybinding support (hjkl, gg/G, n/N, q)

• Rust 1.70+ - Install Rust
• Audio Libraries (Linux): libasound2-dev pkg-config

# Clone the repository git clone git@github.com:coolcode/musix.git cd musix # Build and run cargo run # Or build optimized release version cargo build --release ./target/release/musix

1. Start the player: cargo run
2. Navigate: Use j/k or arrow keys to browse songs
3. Search: Press / and type to find songs instantly
4. Play: Press Enter or Space to play selected song
5. Jump: Use gg (first song) or G (last song)
6. Help: Press x to see all controls
7. Quit: Press q or Esc to exit

MUSIX automatically searches for MP3 files in these directories:

1. ~/Music - Your system's Music directory
2. ./data - Local data folder

# Option 1: Use local data folder mkdir -p ./data cp /path/to/your/music/*.mp3 ./data/ # Option 2: Use system Music directory cp /path/to/your/music/*.mp3 ~/Music/ # Option 3: Create symbolic link ln -s /path/to/your/music ./data

Tip: Press x anytime to view the interactive controls popup!

MUSIX features a clean, 4-panel interface that maximizes space for your music:

┌─────────────────────────────────┐ │ MUSIX │ ← Title Bar ├─────────────────────────────────┤ │ Songs - Search: rock │ ← Song List (Search Mode) │ → ♪ 1. Rock Song │ or "Songs" (Normal Mode) │ 5. Another Rock Song │ (Scrollable, Filtered) │ 12. Rock Ballad │ │ More filtered results... │ ├─────────────────────────────────┤ │ ████████████████░░░░ 02:30/04:15│ ← Progress Bar ├─────────────────────────────────┤ │ Search Mode | Songs: 15/120 |.. │ ← Status & Search Info └─────────────────────────────────┘ 

┌─────────────────────────────────┐ │ CONTROLS │ │ │ │ ↑/↓ or j/k - Navigate songs │ │ Space/↵ - Play/Pause │ │ ←/→ or h/l - Play prev/next song│ │ gg/G - Jump to first/last │ │ / - Enter search mode │ │ n/N - Next/prev search │ │ ,/. - Seek ±5 seconds │ │ r - Toggle random mode │ │ q/Esc - Exit application │ │ x - Close this popup │ └─────────────────────────────────┘ 

• Instant Search: Press / to enter search mode
• Real-time Filtering: Results update as you type
• Fuzzy Matching: Finds songs even with partial or misspelled text
• Smart Scoring: Prioritizes exact matches → substring matches → fuzzy matches
• Search Navigation: Use n/N to quickly jump between results
• Quick Play: Press Enter on any result to play immediately

Example: Searching "btl" will match "Battle Song", "Beautiful", "Subtitle"

• → Currently selected song in the list
• ♪ Currently playing song indicator
• Progress Bar Real-time playback progress with time
• Search Title Shows current search query in song list header
• Result Count Displays filtered results count (e.g., "15/120 songs")

• Normal Mode: Sequential playback through your playlist
• Random Mode: Intelligent shuffle (excludes current song)

• Initial state: Plays the first selected song
• Different song selected: Plays the selected song immediately
• Same song selected: Toggles play/pause for current song

• Movement: hjkl for navigation (h=left, j=down, k=up, l=right)
• Jumping: gg jumps to first song, G jumps to last song
• Search Navigation: n/N for next/previous search results
• Quit: q as alternative to Escape

• Player Engine: State management with smart playback control
• Terminal UI: Ratatui-powered responsive interface
• Audio Engine: Rodio-based high-quality MP3 processing
• Performance: Efficient seeking without playback interruption

• rodio - Professional audio playback and MP3 decoding
• ratatui - Modern terminal user interface framework
• crossterm - Cross-platform terminal control
• rand - Cryptographically secure random shuffle

musix/ ├── src/ │ └── main.rs # Complete application (~700 lines) ├── data/ # MP3 files (optional) ├── .github/workflows/ # CI/CD automation ├── Cargo.toml # Dependencies and metadata ├── rustfmt.toml # Code formatting rules └── README.md # Documentation 

# Development build cargo build # Optimized release build cargo build --release # Run all tests cargo test # Code quality checks cargo clippy --all-targets --all-features -- -D warnings cargo fmt --all -- --check

Issue: No MP3 files found in any accessible directory

Solutions:

# Option 1: Copy files to data folder mkdir -p ./data cp /path/to/your/music/*.mp3 ./data/ # Option 2: Create symbolic link ln -s /path/to/your/music ./data # Option 3: Check permissions ls -la ~/Music

Issue: Cannot access ~/Music directory on macOS

Solution: Enable Full Disk Access for your terminal:

1. System Settings → Privacy & Security → Full Disk Access
2. Click lock icon to unlock settings
3. Click + and add your terminal app (Terminal/iTerm2)
4. Enable the checkbox
5. Restart your terminal

Issue: No audio output or initialization errors

Solutions:

# Install required audio libraries sudo apt-get update sudo apt-get install libasound2-dev pkg-config # For other distributions sudo pacman -S alsa-lib pkg-config # Arch sudo dnf install alsa-lib-devel pkgconf # Fedora

This project is licensed under the MIT License - see the LICENSE file for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

• Rodio team for excellent Rust audio library
• Ratatui team for powerful TUI framework
• Rust community for amazing ecosystem

Built with Claud Code