{"id":30019979,"url":"https://github.com/coolcode/musix","last_synced_at":"2025-08-06T01:36:09.157Z","repository":{"id":306749296,"uuid":"1027033004","full_name":"coolcode/musix","owner":"coolcode","description":"Musix - A minimalist terminal-based MP3 music player built with Rust.","archived":false,"fork":false,"pushed_at":"2025-07-27T11:41:38.000Z","size":27,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-27T12:16:34.238Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coolcode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-27T06:55:04.000Z","updated_at":"2025-07-27T11:41:42.000Z","dependencies_parsed_at":"2025-07-27T12:16:59.909Z","dependency_job_id":"872843c1-68ae-4923-b2ea-21f92e7c3f57","html_url":"https://github.com/coolcode/musix","commit_stats":null,"previous_names":["coolcode/musix"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/coolcode/musix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolcode%2Fmusix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolcode%2Fmusix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolcode%2Fmusix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolcode%2Fmusix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coolcode","download_url":"https://codeload.github.com/coolcode/musix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolcode%2Fmusix/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269005370,"owners_count":24343376,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-05T02:00:12.334Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-06T01:36:05.000Z","updated_at":"2025-08-06T01:36:09.147Z","avatar_url":"https://github.com/coolcode.png","language":"Rust","readme":"# MUSIX\n\nA minimalist terminal-based MP3 music player built with Rust.\n\n![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge\u0026logo=rust\u0026logoColor=white)\n![Terminal](https://img.shields.io/badge/Terminal-UI-green?style=for-the-badge)\n![Music](https://img.shields.io/badge/MP3-Player-orange?style=for-the-badge)\n\n[![asciicast](https://asciinema.org/a/730123.svg)](https://asciinema.org/a/730123)\n\n## Features\n\n- **Beautiful TUI**: Clean terminal interface with cyberpunk green theme\n- **High-Quality Playback**: MP3 audio support with crystal-clear sound\n- **Visual Progress**: Real-time progress bar with time display\n- **Smart Controls**: Intuitive keyboard controls with popup help\n- **Smooth Seeking**: Instant seek without playback interruption\n- **Playback Modes**: Normal sequential and random shuffle\n- **Keyboard-Driven**: Lightning-fast keyboard-only interface\n- **Fuzzy Search**: Real-time search with `/` key - find songs instantly\n- **Vim-Style Navigation**: Full vim keybinding support (hjkl, gg/G, n/N, q)\n\n## Quick Start\n\n### Prerequisites\n\n- **Rust 1.70+** - [Install Rust](https://rustup.rs/)\n- **Audio Libraries** (Linux): `libasound2-dev pkg-config`\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone git@github.com:coolcode/musix.git\ncd musix\n\n# Build and run\ncargo run\n\n# Or build optimized release version\ncargo build --release\n./target/release/musix\n```\n\n### Quick Usage\n1. **Start the player**: `cargo run`\n2. **Navigate**: Use `j/k` or arrow keys to browse songs\n3. **Search**: Press `/` and type to find songs instantly\n4. **Play**: Press `Enter` or `Space` to play selected song\n5. **Jump**: Use `gg` (first song) or `G` (last song)\n6. **Help**: Press `x` to see all controls\n7. **Quit**: Press `q` or `Esc` to exit\n\n### Setup Music Files\n\nMUSIX automatically searches for MP3 files in these directories:\n\n1. **`~/Music`** - Your system's Music directory\n2. **`./data`** - Local data folder\n\n```bash\n# Option 1: Use local data folder\nmkdir -p ./data\ncp /path/to/your/music/*.mp3 ./data/\n\n# Option 2: Use system Music directory\ncp /path/to/your/music/*.mp3 ~/Music/\n\n# Option 3: Create symbolic link\nln -s /path/to/your/music ./data\n```\n\n## Controls\n\n\u003e **Tip**: Press **x** anytime to view the interactive controls popup!\n\n### Essential Keys\n\n| Key | Action |\n|-----|--------|\n| **`Space/↵`** | **Smart Play** - Play selected song or pause current |\n| **`/`** | **Search Mode** - Enter fuzzy search |\n| **`x`** | **Show/Hide help popup** |\n| **`q/Esc`** | **Exit** |\n\n### Navigation \u0026 Playback\n\n| Key | Action |\n|-----|--------|\n| `↑/↓` or `j/k` | Navigate songs (vim-style) |\n| `Space/↵` | Play/pause (same functionality) |\n| `←/→` or `h/l` | Play previous/next song |\n| `gg` / `G` | Jump to first/last song |\n| `,` / `.` | Seek backward/forward 5 seconds |\n| `\u003c` / `\u003e` | Same as above |\n| `r` | Toggle Random mode |\n\n### Search Mode\n\n| Key | Action |\n|-----|--------|\n| **`/`** | Enter search mode |\n| `n` / `N` | Navigate to next/previous search result |\n| `↑/↓` or `j/k` | Navigate through filtered results |\n| `Enter` | Play selected song and exit search |\n| `Esc` | Exit search mode |\n| `Backspace` | Delete characters from search query |\n| `Any text` | Type to search (fuzzy matching) |\n\n## Interface\n\nMUSIX features a clean, 4-panel interface that maximizes space for your music:\n\n```\n┌─────────────────────────────────┐\n│             MUSIX               │  ← Title Bar\n├─────────────────────────────────┤\n│ Songs - Search: rock            │  ← Song List (Search Mode)\n│ → ♪ 1. Rock Song                │    or \"Songs\" (Normal Mode)\n│     5. Another Rock Song        │    (Scrollable, Filtered)\n│     12. Rock Ballad             │\n│     More filtered results...    │\n├─────────────────────────────────┤\n│ ████████████████░░░░ 02:30/04:15│  ← Progress Bar\n├─────────────────────────────────┤\n│ Search Mode | Songs: 15/120 |.. │  ← Status \u0026 Search Info\n└─────────────────────────────────┘\n```\n\n### Interactive Controls Popup (Press **x**)\n\n```\n┌─────────────────────────────────┐\n│            CONTROLS             │\n│                                 │\n│ ↑/↓ or j/k - Navigate songs     │\n│ Space/↵    - Play/Pause         │\n│ ←/→ or h/l - Play prev/next song│\n│ gg/G       - Jump to first/last │\n│ /          - Enter search mode  │\n│ n/N        - Next/prev search   │\n│ ,/.        - Seek ±5 seconds    │\n│ r          - Toggle random mode │\n│ q/Esc      - Exit application   │\n│ x          - Close this popup   │\n└─────────────────────────────────┘\n```\n\n## Smart Features\n\n### Fuzzy Search\n- **Instant Search**: Press `/` to enter search mode\n- **Real-time Filtering**: Results update as you type\n- **Fuzzy Matching**: Finds songs even with partial or misspelled text\n- **Smart Scoring**: Prioritizes exact matches → substring matches → fuzzy matches\n- **Search Navigation**: Use `n/N` to quickly jump between results\n- **Quick Play**: Press Enter on any result to play immediately\n\n**Example**: Searching \"btl\" will match \"Battle Song\", \"Beautiful\", \"Subtitle\"\n\n### Visual Indicators\n- **`→`** Currently selected song in the list\n- **`♪`** Currently playing song indicator  \n- **Progress Bar** Real-time playback progress with time\n- **Search Title** Shows current search query in song list header\n- **Result Count** Displays filtered results count (e.g., \"15/120 songs\")\n\n### Playback Modes\n- **Normal Mode**: Sequential playback through your playlist\n- **Random Mode**: Intelligent shuffle (excludes current song)\n\n### Smart Space/Enter Key\n- **Initial state**: Plays the first selected song\n- **Different song selected**: Plays the selected song immediately\n- **Same song selected**: Toggles play/pause for current song\n\n### Vim-Style Navigation\n- **Movement**: `hjkl` for navigation (h=left, j=down, k=up, l=right)\n- **Jumping**: `gg` jumps to first song, `G` jumps to last song\n- **Search Navigation**: `n/N` for next/previous search results\n- **Quit**: `q` as alternative to Escape\n\n## Technical Details\n\n### Architecture\n- **Player Engine**: State management with smart playback control\n- **Terminal UI**: Ratatui-powered responsive interface  \n- **Audio Engine**: Rodio-based high-quality MP3 processing\n- **Performance**: Efficient seeking without playback interruption\n\n### Core Dependencies\n- **`rodio`** - Professional audio playback and MP3 decoding\n- **`ratatui`** - Modern terminal user interface framework\n- **`crossterm`** - Cross-platform terminal control\n- **`rand`** - Cryptographically secure random shuffle\n\n## Development\n\n### Project Structure\n\n```\nmusix/\n├── src/\n│   └── main.rs          # Complete application (~700 lines)\n├── data/                # MP3 files (optional)\n├── .github/workflows/   # CI/CD automation\n├── Cargo.toml          # Dependencies and metadata\n├── rustfmt.toml        # Code formatting rules\n└── README.md           # Documentation\n```\n\n### Building \u0026 Testing\n\n```bash\n# Development build\ncargo build\n\n# Optimized release build\ncargo build --release\n\n# Run all tests\ncargo test\n\n# Code quality checks\ncargo clippy --all-targets --all-features -- -D warnings\ncargo fmt --all -- --check\n```\n\n## Troubleshooting\n\n### No Music Files Found\n\n**Issue**: `No MP3 files found in any accessible directory`\n\n**Solutions**:\n```bash\n# Option 1: Copy files to data folder\nmkdir -p ./data\ncp /path/to/your/music/*.mp3 ./data/\n\n# Option 2: Create symbolic link\nln -s /path/to/your/music ./data\n\n# Option 3: Check permissions\nls -la ~/Music\n```\n\n### macOS Music Access\n\n**Issue**: Cannot access ~/Music directory on macOS\n\n**Solution**: Enable Full Disk Access for your terminal:\n\n1. **System Settings** → **Privacy \u0026 Security** → **Full Disk Access**\n2. Click lock icon to unlock settings\n3. Click **+** and add your terminal app (Terminal/iTerm2)\n4. Enable the checkbox\n5. **Restart your terminal**\n\n### Linux Audio Issues\n\n**Issue**: No audio output or initialization errors\n\n**Solutions**:\n```bash\n# Install required audio libraries\nsudo apt-get update\nsudo apt-get install libasound2-dev pkg-config\n\n# For other distributions\nsudo pacman -S alsa-lib pkg-config  # Arch\nsudo dnf install alsa-lib-devel pkgconf  # Fedora\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Acknowledgments\n\n- **Rodio** team for excellent Rust audio library\n- **Ratatui** team for powerful TUI framework\n- **Rust** community for amazing ecosystem\n\n---\n\n**Built with Claud Code**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoolcode%2Fmusix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoolcode%2Fmusix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoolcode%2Fmusix/lists"}