{"id":28568461,"url":"https://github.com/dexter-xd/rhythm","last_synced_at":"2025-10-17T05:07:24.315Z","repository":{"id":295551480,"uuid":"990411392","full_name":"dexter-xD/rhythm","owner":"dexter-xD","description":"A modern Linux music player with stunning visualizations.","archived":false,"fork":false,"pushed_at":"2025-08-25T03:36:25.000Z","size":10826,"stargazers_count":100,"open_issues_count":1,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-25T06:42:07.599Z","etag":null,"topics":["c","love2d","lua","mp3-player","mpg123","portaudio","tui"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/dexter-xD.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-05-26T04:41:19.000Z","updated_at":"2025-08-25T06:41:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"915c9f3b-1f50-4ef6-a77c-474d973dc696","html_url":"https://github.com/dexter-xD/rhythm","commit_stats":null,"previous_names":["dexter-xd/rhythm"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dexter-xD/rhythm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dexter-xD%2Frhythm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dexter-xD%2Frhythm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dexter-xD%2Frhythm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dexter-xD%2Frhythm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dexter-xD","download_url":"https://codeload.github.com/dexter-xD/rhythm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dexter-xD%2Frhythm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279287782,"owners_count":26140767,"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-10-17T02:00:07.504Z","response_time":56,"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":["c","love2d","lua","mp3-player","mpg123","portaudio","tui"],"created_at":"2025-06-10T16:12:38.980Z","updated_at":"2025-10-17T05:07:24.308Z","avatar_url":"https://github.com/dexter-xD.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"gui/assets/logo/logo.png\" alt=\"Rhythm Logo\" width=\"128\" height=\"128\"\u003e\n  \n  # Rhythm\n  \n  **A modern Linux music player with stunning visualizations**\n  \n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n  [![C](https://img.shields.io/badge/C-11-blue.svg)](https://en.wikipedia.org/wiki/C11_(C_standard_revision))\n  [![Lua](https://img.shields.io/badge/Lua-5.1-lightblue.svg)](https://www.lua.org/)\n  [![Platform](https://img.shields.io/badge/Platform-Linux-green.svg)](https://www.linux.org/)\n  [![Build System](https://img.shields.io/badge/Build-CMake-red.svg)](https://cmake.org/)\n  [![GUI](https://img.shields.io/badge/GUI-LÖVE2D-purple.svg)](https://love2d.org/)\n  [![Audio](https://img.shields.io/badge/Audio-PortAudio-orange.svg)](http://www.portaudio.com/)\n  [![Decoder](https://img.shields.io/badge/Decoder-mpg123-yellow.svg)](https://www.mpg123.de/)\n  \n  ![Rhythm Banner](banner.png)\n\u003c/div\u003e\n\n## ✨ Features\n\n- 🎵 **Multi-Format Support** - Play MP3, FLAC, and other popular audio formats\n- 🌈 **Stunning Visualizations** - Real-time spectrum analyzer with beautiful effects\n- 🎮 **Dual Interface** - Choose between CLI for simplicity or GUI for rich experience\n- 🐧 **Linux Native** - Optimized for Linux systems with native performance\n- 📁 **Smart Playlist Management** - Load single files or entire directories\n- 🔀 **Advanced Playback** - Shuffle, repeat modes, and seamless track transitions\n- ⚡ **High Performance** - Native C core with optimized audio processing\n- 🎨 **Modern UI** - Clean, responsive interface built with LÖVE2D\n- 🎛️ **Intuitive Controls** - Keyboard shortcuts and mouse interaction\n\n## 🖥️ System Requirements\n\n- **OS**: Linux (Ubuntu, Fedora, Arch, openSUSE)\n- **Architecture**: x86_64\n- **Dependencies**: PortAudio, mpg123, LÖVE2D (for GUI)\n- **Memory**: ~100MB RAM usage\n- **Disk**: ~20MB installation size\n\n## � QInstallation\n\n### Pre-built Debian Packages (Recommended)\n\nWe provide ready-to-install Debian packages for Ubuntu, Debian, and other Debian-based distributions. Choose the package that best fits your needs:\n\n#### Package Options\n\n**🎵 `rhythm-2.0.0-debian-amd64.deb` - Complete Edition (Recommended)**\n- Includes both GUI and terminal interfaces\n- Full feature set with visualizations\n- Best choice for desktop users\n- Size: ~2.4MB\n\n**🖥️ `rhythm-gui-2.0.0-debian-amd64.deb` - GUI Only**\n- Graphical interface with visualizations\n- Perfect for desktop environments\n- Requires LÖVE2D\n- Size: ~2.4MB\n\n**⌨️ `rhythm-tui-2.0.0-debian-amd64.deb` - Terminal Only**\n- Lightweight terminal interface\n- Ideal for servers and minimal systems\n- No GUI dependencies required\n- Size: ~20KB\n\n#### Installation Steps\n\n1. **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\n\n2. **Install the package:**\n   ```bash\n   # For the complete edition (recommended)\n   sudo dpkg -i rhythm-2.0.0-debian-amd64.deb\n   \n   # For GUI-only version\n   sudo dpkg -i rhythm-gui-2.0.0-debian-amd64.deb\n   \n   # For terminal-only version\n   sudo dpkg -i rhythm-tui-2.0.0-debian-amd64.deb\n   ```\n\n3. **Install dependencies** (if any are missing):\n   ```bash\n   sudo apt-get install -f\n   ```\n\n4. **Launch Rhythm:**\n   ```bash\n   # Complete or GUI version\n   rhythm                    # Launches GUI\n   rhythm-cli               # Launches terminal interface (complete edition only)\n   \n   # Terminal-only version\n   rhythm                   # Launches terminal interface\n   ```\n\n#### System Requirements for Packages\n\n**All Packages:**\n- Ubuntu 18.04+ / Debian 10+ / Linux Mint 19+\n- x86_64 architecture\n- PortAudio and mpg123 libraries (auto-installed)\n\n**GUI Packages Additional Requirements:**\n- LÖVE2D 11.0+ (auto-installed)\n- Desktop environment (GNOME, KDE, XFCE, etc.)\n- Graphics drivers with OpenGL support\n\n#### Verifying Installation\n\nAfter installation, verify that Rhythm is working correctly:\n\n```bash\n# Check if the command is available\nwhich rhythm\n\n# Test with version info\nrhythm --version\n\n# For complete edition, test both interfaces\nrhythm --help              # GUI version help\nrhythm-cli --help          # Terminal version help (only for complete edition)\n```\n\n**Desktop Integration:**\n- The GUI version will appear in your application menu under \"Sound \u0026 Video\"\n- Look for \"Rhythm Music Player\" with the Rhythm logo\n- You can also launch it from the command line with `rhythm`\n\n#### Uninstallation\n\n```bash\n# Remove the installed package\nsudo dpkg -r rhythm        # Complete edition\nsudo dpkg -r rhythm-gui    # GUI-only edition  \nsudo dpkg -r rhythm-tui    # Terminal-only edition\n\n# Remove configuration files (optional)\nsudo dpkg --purge rhythm\n```\n\n### Alternative Installation Methods\n\nIf the pre-built packages don't work for your system, you can build from source:\n\n## 🚀 Build from Source\n\n### What is LÖVE2D?\n\nLÖ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.\n\n### Install Dependencies\n\n**Ubuntu/Debian:**\n```bash\n# Core dependencies for CLI\nsudo apt update \u0026\u0026 sudo apt install -y \\\n    portaudio19-dev libmpg123-dev cmake build-essential\n\n# For GUI support, install LÖVE2D\nsudo apt install -y love\n```\n\n**Fedora/RHEL:**\n```bash\n# Core dependencies for CLI\nsudo dnf install -y \\\n    portaudio-devel mpg123-devel cmake gcc\n\n# For GUI support, install LÖVE2D\nsudo dnf install -y love\n```\n\n**Arch Linux:**\n```bash\n# Core dependencies for CLI\nsudo pacman -S \\\n    portaudio mpg123 cmake gcc\n\n# For GUI support, install LÖVE2D\nsudo pacman -S love\n```\n\n**Alternative LÖVE2D Installation:**\nIf LÖVE2D is not available in your package manager, download from [love2d.org](https://love2d.org/):\n```bash\n# Download and install LÖVE2D AppImage (works on most Linux distros)\nwget https://github.com/love2d/love/releases/download/11.4/love-11.4-x86_64.AppImage\nchmod +x love-11.4-x86_64.AppImage\nsudo mv love-11.4-x86_64.AppImage /usr/local/bin/love\n```\n\n### Prerequisites for Building\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/rhythm.git\ncd rhythm\n\n# Build the project\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake\n\n# Install (optional)\nsudo make install\n```\n\n## 🎮 Usage\n\n### CLI Mode (Terminal)\n\n**Play a single file:**\n```bash\n./rhythm song.mp3\n```\n\n**Play entire directory:**\n```bash\n./rhythm /path/to/music/folder\n```\n\n**CLI Controls:**\n- **Space** - Play/Pause\n- **q** - Quit\n- **+/-** - Volume control\n- **→/←** - Next/Previous track\n- **s** - Stop playback\n- **m** - Toggle mute\n\n### GUI Mode (Visual Interface)\n\n**Launch GUI:**\n```bash\n# From the project root directory\nlove gui\n\n# Alternative: if you're in the gui directory\ncd gui\nlove .\n```\n\n**Note:** Make sure you have LÖVE2D installed (see installation instructions above)\n\n**GUI Features:**\n- 🎨 **Beautiful Visualizer** - Real-time spectrum analysis with particle effects\n- 🎵 **Song Information** - Display current track, artist, and album\n- 🎛️ **Interactive Controls** - Click-to-seek progress bar, volume slider\n- 🔀 **Playback Modes** - Shuffle and repeat controls\n- 📱 **Responsive Design** - Adapts to different window sizes\n\n**GUI Controls:**\n- **Mouse** - Click buttons, drag volume slider, seek in progress bar\n- **Space** - Play/Pause\n- **←/→** - Previous/Next track\n- **↑/↓** - Volume control\n- **S** - Stop\n- **M** - Mute/Unmute\n- **Escape** - Exit application\n\n## 🏗️ Architecture\n\n### Core Engine (C)\n- **Audio Player** - Low-latency audio playback with PortAudio\n- **Decoder** - Multi-format audio decoding with mpg123\n- **Playlist Manager** - Smart track management and navigation\n- **Spectrum Analyzer** - Real-time FFT analysis for visualizations\n\n### GUI Interface (Lua/LÖVE2D)\n- **Game State** - Centralized state management\n- **UI Components** - Modular player, controls, and visualizer\n- **Engine Bridge** - Seamless C ↔ Lua communication\n- **Theme System** - Modern dark theme with glassmorphism effects\n\n## 🎨 Visualizations\n\nThe GUI features multiple visualization modes:\n\n- **Spectrum Bars** - Classic frequency spectrum display\n- **Waveform** - Real-time audio waveform\n- **Particle Effects** - Audio-reactive particle systems\n- **Galactic Journey** - Immersive space-themed background\n- **Floating Elements** - Dynamic UI elements that respond to music\n\n## 🔧 Development\n\n### Project Structure\n```\nrhythm/\n├── src/core/          # C audio engine\n├── src/cli/           # Terminal interface\n├── gui/               # LÖVE2D GUI application\n├── include/           # Header files\n├── tests/             # Unit tests\n└── build/             # Build artifacts\n```\n\n### Building Components\n\n**CLI Only:**\n```bash\ncmake -DBUILD_CLI=ON -DBUILD_GUI=OFF ..\nmake\n```\n\n**GUI Development:**\n```bash\n# Run GUI directly for development (from project root)\nlove gui\n\n# Or from gui directory\ncd gui \u0026\u0026 love .\n\n# For live development with file watching\nlove gui --console\n```\n\n**Run Tests:**\n```bash\nmake test\n```\n\n## 🎵 Supported Formats\n\n- **MP3** - MPEG-1/2 Audio Layer III\n- **FLAC** - Free Lossless Audio Codec (planned)\n- **OGG** - Ogg Vorbis (planned)\n- **WAV** - Waveform Audio File Format (planned)\n\n## 🔧 Troubleshooting\n\n### LÖVE2D Issues\n\n**\"love: command not found\"**\n```bash\n# Check if LÖVE2D is installed\nwhich love\n\n# If not installed, install it:\nsudo apt install love  # Ubuntu/Debian\nsudo dnf install love  # Fedora\nsudo pacman -S love    # Arch\n\n# Or download AppImage from love2d.org\n```\n\n**GUI won't start**\n```bash\n# Make sure you're in the project root directory\npwd  # Should show /path/to/rhythm\n\n# Run from project root\nlove gui\n\n# Check for error messages\nlove gui --console\n```\n\n**Audio not working in GUI**\n- Ensure the C engine is built: `make` in the build directory\n- Check that `librhythm_engine.so` exists in the build directory\n- Verify audio permissions and PulseAudio/ALSA setup\n\n## 🤝 Contributing\n\nWe welcome contributions from the community! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.\n\n**Quick Start:**\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n**Development Areas:**\n- 🎵 Audio format support expansion\n- 🎨 New visualization effects\n- 🔧 Performance optimizations\n- 📱 UI/UX improvements\n- 🧪 Test coverage expansion\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [PortAudio](http://www.portaudio.com/) for cross-platform audio I/O\n- [mpg123](https://www.mpg123.de/) for reliable MP3 decoding\n- [LÖVE2D](https://love2d.org/) for the excellent 2D game framework\n- [Lua](https://www.lua.org/) for the lightweight scripting language\n- The open-source community for inspiration and support\n\n## 📞 Support\n\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/your-username/rhythm/issues)\n- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/your-username/rhythm/discussions)\n- 💬 **Community Chat**: [Discord Server](https://discord.gg/P48cY9zFal)\n- 📧 **Contact**: [GitHub Profile](https://github.com/your-username)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003e🎵 Enjoy your music with Rhythm! 🎵\u003c/strong\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdexter-xd%2Frhythm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdexter-xd%2Frhythm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdexter-xd%2Frhythm/lists"}