https://github.com/dexter-xd/rhythm
A modern Linux music player with stunning visualizations.
https://github.com/dexter-xd/rhythm
c love2d lua mp3-player mpg123 portaudio tui
Last synced: 2 months ago
JSON representation
A modern Linux music player with stunning visualizations.
- Host: GitHub
- URL: https://github.com/dexter-xd/rhythm
- Owner: dexter-xD
- License: mit
- Created: 2025-05-26T04:41:19.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-08-25T03:36:25.000Z (4 months ago)
- Last Synced: 2025-08-25T06:42:07.599Z (4 months ago)
- Topics: c, love2d, lua, mp3-player, mpg123, portaudio, tui
- Language: Lua
- Homepage:
- Size: 10.3 MB
- Stars: 100
- Watchers: 1
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Rhythm
**A modern Linux music player with stunning visualizations**
[](https://opensource.org/licenses/MIT)
[](https://en.wikipedia.org/wiki/C11_(C_standard_revision))
[](https://www.lua.org/)
[](https://www.linux.org/)
[](https://cmake.org/)
[](https://love2d.org/)
[](http://www.portaudio.com/)
[](https://www.mpg123.de/)
## โจ Features
- ๐ต **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
## ๐ฅ๏ธ System Requirements
- **OS**: Linux (Ubuntu, Fedora, Arch, openSUSE)
- **Architecture**: x86_64
- **Dependencies**: PortAudio, mpg123, LรVE2D (for GUI)
- **Memory**: ~100MB RAM usage
- **Disk**: ~20MB installation size
## ๏ฟฝ QInstallation
### Pre-built Debian Packages (Recommended)
We provide ready-to-install Debian packages for Ubuntu, Debian, and other Debian-based distributions. Choose the package that best fits your needs:
#### Package Options
**๐ต `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
#### Installation Steps
1. **Download the package** that matches your preference from the [Releases]([https://github.com/your-username/rhythm/release](https://github.com/dexter-xD/rhythm/releases/tag/v2.0.0)s) page
2. **Install the package:**
```bash
# 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):
```bash
sudo apt-get install -f
```
4. **Launch Rhythm:**
```bash
# Complete or GUI version
rhythm # Launches GUI
rhythm-cli # Launches terminal interface (complete edition only)
# Terminal-only version
rhythm # Launches terminal interface
```
#### System Requirements for Packages
**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
#### Verifying Installation
After installation, verify that Rhythm is working correctly:
```bash
# 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`
#### Uninstallation
```bash
# 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
```
### Alternative Installation Methods
If the pre-built packages don't work for your system, you can build from source:
## ๐ Build from Source
### What is LรVE2D?
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.
### Install Dependencies
**Ubuntu/Debian:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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](https://love2d.org/):
```bash
# 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
```
### Prerequisites for Building
```bash
# 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
```
## ๐ฎ Usage
### CLI Mode (Terminal)
**Play a single file:**
```bash
./rhythm song.mp3
```
**Play entire directory:**
```bash
./rhythm /path/to/music/folder
```
**CLI Controls:**
- **Space** - Play/Pause
- **q** - Quit
- **+/-** - Volume control
- **โ/โ** - Next/Previous track
- **s** - Stop playback
- **m** - Toggle mute
### GUI Mode (Visual Interface)
**Launch GUI:**
```bash
# 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
## ๐๏ธ Architecture
### Core Engine (C)
- **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
### GUI Interface (Lua/LรVE2D)
- **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
## ๐จ Visualizations
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
## ๐ง Development
### Project Structure
```
rhythm/
โโโ src/core/ # C audio engine
โโโ src/cli/ # Terminal interface
โโโ gui/ # LรVE2D GUI application
โโโ include/ # Header files
โโโ tests/ # Unit tests
โโโ build/ # Build artifacts
```
### Building Components
**CLI Only:**
```bash
cmake -DBUILD_CLI=ON -DBUILD_GUI=OFF ..
make
```
**GUI Development:**
```bash
# 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:**
```bash
make test
```
## ๐ต Supported Formats
- **MP3** - MPEG-1/2 Audio Layer III
- **FLAC** - Free Lossless Audio Codec (planned)
- **OGG** - Ogg Vorbis (planned)
- **WAV** - Waveform Audio File Format (planned)
## ๐ง Troubleshooting
### LรVE2D Issues
**"love: command not found"**
```bash
# 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**
```bash
# 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
## ๐ค Contributing
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
## ๐ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## ๐ Acknowledgments
- [PortAudio](http://www.portaudio.com/) for cross-platform audio I/O
- [mpg123](https://www.mpg123.de/) for reliable MP3 decoding
- [LรVE2D](https://love2d.org/) for the excellent 2D game framework
- [Lua](https://www.lua.org/) for the lightweight scripting language
- The open-source community for inspiration and support
## ๐ Support
- ๐ **Bug Reports**: [GitHub Issues](https://github.com/your-username/rhythm/issues)
- ๐ก **Feature Requests**: [GitHub Discussions](https://github.com/your-username/rhythm/discussions)
- ๐ฌ **Community Chat**: [Discord Server](https://discord.gg/P48cY9zFal)
- ๐ง **Contact**: [GitHub Profile](https://github.com/your-username)
---
๐ต Enjoy your music with Rhythm! ๐ต