🎵 Jukebox CLI

A beautiful terminal-based music jukebox application built with Rust and Ratatui. Features an animated visual interface with floating musical notes and intuitive controls.

✨ Features

• 🎶 Visual Jukebox Interface: Beautiful background image with animated musical notes
• 📱 Responsive UI: Adapts to terminal size with scrollable playlist
• ⏯️ Full Playback Control: Play, pause, resume, skip tracks
• 🔊 Volume Control: Adjustable volume with visual feedback
• 📊 Progress Tracking: Real-time progress bars for song duration and volume
• 🎨 Colorful Interface: Each song has its own color in the playlist

🚀 Installation

Prerequisites

• Rust 1.70+ (install from rustup.rs)
• Terminal that supports 256 colors and Unicode

Build from Source

git clone https://github.com/FedeCarollo/jukebox-cli.git
cd jukebox-cli
cargo build --release

🎮 Usage

Basic Usage

# Use default music directory (example_music)
cargo run

# Specify custom music directory
cargo run -- /path/to/your/music

# Show help
cargo run -- --help

Controls

Key	Action
q	Quit application
p / Enter	Play/Resume current song
s	Pause playback
↑ / ↓	Navigate playlist
+ / -	Adjust volume

🎨 Interface Layout

┌─────────────────────────────┬─────────────────┐
│                             │   📋 Playlist   │
│    🎵 Jukebox Display       │   ♪ Song 1      │
│     (with animated          │   ♫ Song 2      │
│      floating notes)        │   ♬ Song 3      │
│                             │   ...           │
├─────────────────┬───────────┤                 │
│   🎮 Controls   │ 📊 Info   │                 │
│ q-Quit p-Play   │ ▓▓▓░░ 60% │                 │
│ ↑↓-Navigate     │ 🔊 75%    │                 │
└─────────────────┴───────────┴─────────────────┘

🔧 Features in Detail

Visual Interface

• Jukebox Background: Customizable PNG background that fills the main display area
• Animated Notes: Musical note sprites that appear randomly during playback
• Responsive Layout: Automatically adjusts to terminal dimensions

Playlist Management

• Circular Navigation: Navigate seamlessly from last to first song and vice versa
• Auto-advance: Automatically plays next song when current song ends
• Visual Indicators: Selected song is underlined, playing song is highlighted

Audio Features

• Format Support: MP3 files via Symphonia decoder
• Volume Control: 0-100% volume with emoji indicators (🔇🔈🔉🔊)
• Progress Tracking: Real-time display of current position and total duration

Performance

• Efficient Rendering: Background caching and optimized note generation
• Responsive Controls: Non-blocking input handling
• Memory Management: Automatic cleanup of expired visual elements

🛠️ Technical Details

Built With

• Rust
• Ratatui: Terminal UI framework
• Rodio: Audio playback library
• Symphonia: Audio format decoder
• Crossterm: Cross-platform terminal manipulation
• Image: Image processing for visual assets

Architecture

• Modular Design: Separated UI components and audio logic
• State Management: Centralized jukebox state with canvas rendering
• Real-time Updates: Fully handled UI updates with frame rendering

📋 Requirements

System Requirements

• OS: Windows, macOS, or Linux
• Terminal: Support for 256 colors and Unicode characters
• Audio: System audio output capability

Dependencies

All dependencies are managed by Cargo and will be installed automatically.

🖼️ Customizing Visual Assets

Adding Your Own Jukebox Background

1. Prepare the Image:
2. Any image format supported by the image crate (PNG, JPEG, GIF, etc.)
3. Recommended: High resolution for better terminal display

4. The image will be automatically resized to fit your terminal

5. Replace the Background: bash # Replace the default jukebox background cp your-jukebox-image.png img/jukebox.png

Adding Custom Musical Notes

1. Prepare Note Images:
2. Format: PNG files (for transparency support)
3. Size: 16x16 pixels (will be randomly resized to 6x6-12x12 during playback)
4. Transparency: Use alpha channel for proper note rendering

5. Content: Musical note symbols, treble clefs, or any musical imagery

6. Add Note Images: bash # Add your custom notes to the notes directory cp note-treble.png img/notes/ cp note-quarter.png img/notes/ cp note-eighth.png img/notes/ # ... add as many as you want

7. Note Behavior:

8. All PNG files in img/notes/ are automatically loaded
9. Notes are randomly selected during playback
10. Each note is randomly resized between 6x6 and 12x12 pixels
11. Transparent pixels are preserved for proper overlay on jukebox background

Tips for Best Results

• Jukebox Background: Use images with good contrast for better text readability
• Musical Notes: Create notes with distinct colors for visual variety
• File Names: Any valid filename works (e.g., treble.png, quarter-note.png)
• Quantity: Add 5-10 different note designs for good visual variety

Example Note Collection

img/notes/
├── treble-clef.png
├── quarter-note.png
├── eighth-note.png
├── musical-staff.png
└── sharp-symbol.png

📄 License

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

🙏 Acknowledgments

• Built with the amazing Rust ecosystem
• Inspired by classic jukebox interfaces
• Musical note assets and jukebox imagery

🐛 Troubleshooting

Common Issues

No songs detected - Jukebox-cli supports only mp3 files as of now - Ensure MP3 files are in the specified directory - Check file permissions

Visual artifacts - Ensure terminal supports 256 colors - Try resizing terminal window

Audio not playing - Check system audio settings - Ensure audio output device is available

Performance issues - Try reducing terminal size

---

Made with ❤️ and 🎵 in Rust