MUSIX

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

Features

• 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)

Quick Start

Prerequisites

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

Installation

# 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

Quick Usage

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

Setup Music Files

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

Controls

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

Essential Keys

Key	Action
Space/↵	Smart Play - Play selected song or pause current
/	Search Mode - Enter fuzzy search
x	Show/Hide help popup
q/Esc	Exit

Navigation & Playback

Key	Action
↑/↓ or j/k	Navigate songs (vim-style)
Space/↵	Play/pause (same functionality)
←/→ or h/l	Play previous/next song
gg / G	Jump to first/last song
, / .	Seek backward/forward 5 seconds
< / >	Same as above
r	Toggle Random mode

Search Mode

Key	Action
/	Enter search mode
n / N	Navigate to next/previous search result
↑/↓ or j/k	Navigate through filtered results
Enter	Play selected song and exit search
Esc	Exit search mode
Backspace	Delete characters from search query
Any text	Type to search (fuzzy matching)

Interface

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
└─────────────────────────────────┘

Interactive Controls Popup (Press x)

┌─────────────────────────────────┐
│            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   │
└─────────────────────────────────┘

Smart Features

Fuzzy Search

• 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"

Visual Indicators

• → 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")

Playback Modes

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

Smart Space/Enter Key

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

Vim-Style Navigation

• 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

Technical Details

Architecture

• 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

Core Dependencies

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

Development

Project Structure

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

Building & Testing

# 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

Troubleshooting

No Music Files Found

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

macOS Music Access

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

Linux Audio Issues

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

License

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

Contributing

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

Acknowledgments

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

---

Built with Claud Code