Rhythm

A modern Linux music player with stunning visualizations

• 🎵 Multi-Format Support - Play MP3, FLAC, and other popular audio formats
• 🌈 Stunning Visualizations - Real-time spectrum analyzer with beautiful effects
• 🎮 Dual Interface - Choose between CLI for simplicity or GUI for rich experience
• 🐧 Linux Native - Optimized for Linux systems with native performance
• 📁 Smart Playlist Management - Load single files or entire directories
• 🔀 Advanced Playback - Shuffle, repeat modes, and seamless track transitions
• ⚡ High Performance - Native C core with optimized audio processing
• 🎨 Modern UI - Clean, responsive interface built with LÖVE2D
• 🎛️ Intuitive Controls - Keyboard shortcuts and mouse interaction

• OS: Linux (Ubuntu, Fedora, Arch, openSUSE)
• Architecture: x86_64
• Dependencies: PortAudio, mpg123, LÖVE2D (for GUI)
• Memory: ~100MB RAM usage
• Disk: ~20MB installation size

We provide ready-to-install Debian packages for Ubuntu, Debian, and other Debian-based distributions. Choose the package that best fits your needs:

🎵 rhythm-2.0.0-debian-amd64.deb - Complete Edition (Recommended)

• Includes both GUI and terminal interfaces
• Full feature set with visualizations
• Best choice for desktop users
• Size: ~2.4MB

🖥️ rhythm-gui-2.0.0-debian-amd64.deb - GUI Only

• Graphical interface with visualizations
• Perfect for desktop environments
• Requires LÖVE2D
• Size: ~2.4MB

⌨️ rhythm-tui-2.0.0-debian-amd64.deb - Terminal Only

• Lightweight terminal interface
• Ideal for servers and minimal systems
• No GUI dependencies required
• Size: ~20KB

1. Download the package that matches your preference from the Releases page

2. Install the package:

   # For the complete edition (recommended)
   sudo dpkg -i rhythm-2.0.0-debian-amd64.deb
   
   # For GUI-only version
   sudo dpkg -i rhythm-gui-2.0.0-debian-amd64.deb
   
   # For terminal-only version
   sudo dpkg -i rhythm-tui-2.0.0-debian-amd64.deb

3. Install dependencies (if any are missing):

   sudo apt-get install -f

4. Launch Rhythm:

   # Complete or GUI version
   rhythm                    # Launches GUI
   rhythm-cli               # Launches terminal interface (complete edition only)
   
   # Terminal-only version
   rhythm                   # Launches terminal interface

All Packages:

• Ubuntu 18.04+ / Debian 10+ / Linux Mint 19+
• x86_64 architecture
• PortAudio and mpg123 libraries (auto-installed)

GUI Packages Additional Requirements:

• LÖVE2D 11.0+ (auto-installed)
• Desktop environment (GNOME, KDE, XFCE, etc.)
• Graphics drivers with OpenGL support

After installation, verify that Rhythm is working correctly:

# Check if the command is available
which rhythm

# Test with version info
rhythm --version

# For complete edition, test both interfaces
rhythm --help              # GUI version help
rhythm-cli --help          # Terminal version help (only for complete edition)

Desktop Integration:

• The GUI version will appear in your application menu under "Sound & Video"
• Look for "Rhythm Music Player" with the Rhythm logo
• You can also launch it from the command line with rhythm

# Remove the installed package
sudo dpkg -r rhythm        # Complete edition
sudo dpkg -r rhythm-gui    # GUI-only edition  
sudo dpkg -r rhythm-tui    # Terminal-only edition

# Remove configuration files (optional)
sudo dpkg --purge rhythm

If the pre-built packages don't work for your system, you can build from source:

LÖVE2D (also known as "Love") is a 2D game framework for Lua. We use it to create the beautiful GUI interface for Rhythm. The command love gui tells LÖVE2D to run the application in the gui directory.

Ubuntu/Debian:

# Core dependencies for CLI
sudo apt update && sudo apt install -y \
    portaudio19-dev libmpg123-dev cmake build-essential

# For GUI support, install LÖVE2D
sudo apt install -y love

Fedora/RHEL:

# Core dependencies for CLI
sudo dnf install -y \
    portaudio-devel mpg123-devel cmake gcc

# For GUI support, install LÖVE2D
sudo dnf install -y love

Arch Linux:

# Core dependencies for CLI
sudo pacman -S \
    portaudio mpg123 cmake gcc

# For GUI support, install LÖVE2D
sudo pacman -S love

Alternative LÖVE2D Installation: If LÖVE2D is not available in your package manager, download from love2d.org:

# Download and install LÖVE2D AppImage (works on most Linux distros)
wget https://github.com/love2d/love/releases/download/11.4/love-11.4-x86_64.AppImage
chmod +x love-11.4-x86_64.AppImage
sudo mv love-11.4-x86_64.AppImage /usr/local/bin/love

# Clone the repository
git clone https://github.com/your-username/rhythm.git
cd rhythm

# Build the project
mkdir build && cd build
cmake ..
make

# Install (optional)
sudo make install

Play a single file:

./rhythm song.mp3

Play entire directory:

./rhythm /path/to/music/folder

CLI Controls:

• Space - Play/Pause
• q - Quit
• +/- - Volume control
• →/← - Next/Previous track
• s - Stop playback
• m - Toggle mute

Launch GUI:

# From the project root directory
love gui

# Alternative: if you're in the gui directory
cd gui
love .

Note: Make sure you have LÖVE2D installed (see installation instructions above)

GUI Features:

• 🎨 Beautiful Visualizer - Real-time spectrum analysis with particle effects
• 🎵 Song Information - Display current track, artist, and album
• 🎛️ Interactive Controls - Click-to-seek progress bar, volume slider
• 🔀 Playback Modes - Shuffle and repeat controls
• 📱 Responsive Design - Adapts to different window sizes

GUI Controls:

• Mouse - Click buttons, drag volume slider, seek in progress bar
• Space - Play/Pause
• ←/→ - Previous/Next track
• ↑/↓ - Volume control
• S - Stop
• M - Mute/Unmute
• Escape - Exit application

• Audio Player - Low-latency audio playback with PortAudio
• Decoder - Multi-format audio decoding with mpg123
• Playlist Manager - Smart track management and navigation
• Spectrum Analyzer - Real-time FFT analysis for visualizations

• Game State - Centralized state management
• UI Components - Modular player, controls, and visualizer
• Engine Bridge - Seamless C ↔ Lua communication
• Theme System - Modern dark theme with glassmorphism effects

The GUI features multiple visualization modes:

• Spectrum Bars - Classic frequency spectrum display
• Waveform - Real-time audio waveform
• Particle Effects - Audio-reactive particle systems
• Galactic Journey - Immersive space-themed background
• Floating Elements - Dynamic UI elements that respond to music

rhythm/
├── src/core/          # C audio engine
├── src/cli/           # Terminal interface
├── gui/               # LÖVE2D GUI application
├── include/           # Header files
├── tests/             # Unit tests
└── build/             # Build artifacts

CLI Only:

cmake -DBUILD_CLI=ON -DBUILD_GUI=OFF ..
make

GUI Development:

# Run GUI directly for development (from project root)
love gui

# Or from gui directory
cd gui && love .

# For live development with file watching
love gui --console

Run Tests:

make test

• MP3 - MPEG-1/2 Audio Layer III
• FLAC - Free Lossless Audio Codec (planned)
• OGG - Ogg Vorbis (planned)
• WAV - Waveform Audio File Format (planned)

"love: command not found"

# Check if LÖVE2D is installed
which love

# If not installed, install it:
sudo apt install love  # Ubuntu/Debian
sudo dnf install love  # Fedora
sudo pacman -S love    # Arch

# Or download AppImage from love2d.org

GUI won't start

# Make sure you're in the project root directory
pwd  # Should show /path/to/rhythm

# Run from project root
love gui

# Check for error messages
love gui --console

Audio not working in GUI

• Ensure the C engine is built: make in the build directory
• Check that librhythm_engine.so exists in the build directory
• Verify audio permissions and PulseAudio/ALSA setup

We welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Quick Start:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Areas:

• 🎵 Audio format support expansion
• 🎨 New visualization effects
• 🔧 Performance optimizations
• 📱 UI/UX improvements
• 🧪 Test coverage expansion

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

• PortAudio for cross-platform audio I/O
• mpg123 for reliable MP3 decoding
• LÖVE2D for the excellent 2D game framework
• Lua for the lightweight scripting language
• The open-source community for inspiration and support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 💬 Community Chat: Discord Server
• 📧 Contact: GitHub Profile