{"id":29822867,"url":"https://github.com/aakrishtsp/lyrics-on-terminal","last_synced_at":"2025-07-29T01:11:15.792Z","repository":{"id":305527527,"uuid":"932721510","full_name":"AakrishtSP/lyrics-on-terminal","owner":"AakrishtSP","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-20T15:13:22.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-20T17:23:20.134Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AakrishtSP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-02-14T11:55:33.000Z","updated_at":"2025-07-20T15:13:25.000Z","dependencies_parsed_at":"2025-07-20T17:35:29.537Z","dependency_job_id":null,"html_url":"https://github.com/AakrishtSP/lyrics-on-terminal","commit_stats":null,"previous_names":["aakrishtsp/lyrics-on-terminal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/AakrishtSP/lyrics-on-terminal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AakrishtSP%2Flyrics-on-terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AakrishtSP%2Flyrics-on-terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AakrishtSP%2Flyrics-on-terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AakrishtSP%2Flyrics-on-terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AakrishtSP","download_url":"https://codeload.github.com/AakrishtSP/lyrics-on-terminal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AakrishtSP%2Flyrics-on-terminal/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267613749,"owners_count":24115677,"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-07-28T02:00:09.689Z","response_time":68,"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-07-29T01:11:10.348Z","updated_at":"2025-07-29T01:11:15.780Z","avatar_url":"https://github.com/AakrishtSP.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lyrics On Terminal\n\nA real-time lyrics display application for your terminal that syncs with media players via MPRIS2. Watch synchronized lyrics appear as your songs play, all from the comfort of your terminal.\n\n## Features\n\n- **Real-time synchronized lyrics** - Displays time-synced lyrics that follow along with your music\n- **Multiple media player support** - Works with Spotify, VLC, Rhythmbox, Clementine, and other MPRIS2-compatible players\n- **Configurable appearance** - Customize colors, fonts, and UI elements through YAML configuration\n- **Automatic lyrics fetching** - Retrieves lyrics from LrcLib API with fallback search capabilities\n- **Progress tracking** - Shows song progress with a visual progress bar and time indicators\n- **Responsive design** - Adapts to terminal window resizing\n- **Hex color support** - Supports both named colors and hex color codes for advanced theming\n\n## Installation\n\n### Prerequisites\n\n- Python 3.7+\n- Linux system with D-Bus support\n- A media player that supports MPRIS2 (Spotify, VLC, etc.)\n\n### Dependencies\n\nInstall required Python packages:\n\n```bash\npip install -r requirements.txt\n```\n\n### Setup\n\n1. Clone this repository:\n```bash\ngit clone https://github.com/AakrishtSP/Lyrics-On-Terminal.git\ncd Lyrics-On-Terminal\n```\n\n2. Run the application:\n```bash\npython main.py\n```\n\n## Usage\n\n1. Start your preferred media player (Spotify, VLC, etc.)\n2. Begin playing a song\n3. Run the lyrics player:\n   ```bash\n   python main.py\n   ```\n4. The application will automatically detect your media player and display synchronized lyrics\n5. Press `q` to quit the application\n\n### Controls\n\n- `q` - Quit the application\n- Terminal resizing is automatically handled\n\n## Configuration\n\nThe application uses a YAML configuration file located at:\n- `~/.config/lyrics_player/config.yaml` (primary location)\n- `./config.yaml` (local directory)\n\n### Configuration Options\n\n#### Player Priority\nSet the priority order for media player detection:\n```yaml\nplayer_priority:\n  - spotify\n  - vlc\n  - rhythmbox\n  - clementine\n```\n\n#### Colors and Styling\nCustomize the appearance of different UI elements:\n```yaml\ncolors:\n  clock:\n    fg: cyan\n    attrs: [bold]\n  song_info:\n    fg: magenta\n    attrs: [bold]\n  progress_bar:\n    fg: white\n    attrs: []\n  past_lyrics:\n    fg: yellow\n    attrs: []\n  current_lyric:\n    fg: blue\n    attrs: [bold]\n  future_lyrics:\n    fg: white\n    attrs: []\n  progress_time:\n    fg: white\n    attrs: []\n```\n\n**Color Options:**\n- Named colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `default`\n- Hex colors: `#ff0000`, `#00ff00`, etc.\n- 256-color codes: Integer values\n\n**Attributes:**\n- `bold` - Bold text\n- `underline` - Underlined text\n- `italic` - Italic text (if supported by terminal)\n- `standout` - Standout mode\n\n#### UI Customization\n```yaml\nui:\n  progress_bar_filled: \"▓\"\n  progress_bar_unfilled: \"░\"\n  time_format: \"%H:%M:%S\"\n  song_duration_format: \"{minutes:02d}:{seconds:02d}\"\n```\n\n#### User Agent\nCustomize the user agent for API requests:\n```yaml\nuser_agent: \"LyricsTerminalPlayer/1.0 (https://github.com/yourusername/lyrics-player)\"\n```\n\n## File Structure\n\n- `main.py` - Main application entry point and lyrics display logic\n- `config_handler.py` - Configuration management and default settings\n- `config.yaml` - User configuration file\n- `logging.conf` - Logging configuration for debugging\n- `lyrics_player.log` - Application log file\n\n## How It Works\n\n1. **Media Player Detection**: Uses D-Bus to communicate with MPRIS2-compatible media players\n2. **Metadata Extraction**: Retrieves song information (artist, title, album, duration, position)\n3. **Lyrics Fetching**: Queries LrcLib API for synchronized lyrics using song metadata\n4. **Synchronization**: Matches lyrics timestamps with current playback position\n5. **Display**: Renders lyrics in terminal with highlighting for current line\n\n## Troubleshooting\n\n### No lyrics found\n- Ensure your song metadata (artist, title) is accurate\n- Some songs may not have synchronized lyrics available in the LrcLib database\n- Check the log file for API errors: `cat lyrics_player.log`\n\n### Media player not detected\n- Verify your media player supports MPRIS2\n- Check if the player is running and playing music\n- Ensure D-Bus is properly configured on your system\n\n### Configuration not loading\n- Check file permissions for the config file\n- Verify YAML syntax is correct\n- Default configuration will be created if none exists\n\n### Terminal display issues\n- Ensure your terminal supports Unicode characters for progress bars\n- Check terminal color support (256-color recommended)\n- Resize terminal if text appears cut off\n\n## Logging\n\nLogging is configured via `logging.conf`. Logs are written to:\n- `lyrics_player.log` (debug mode)\n- `/tmp/lyrics_player.log` (normal mode)\n\nLog levels can be adjusted in the configuration file for debugging purposes.\n\n## Dependencies\n\n- **dbus-python**: D-Bus communication with media players\n- **lrclib**: Lyrics fetching from LrcLib API\n- **PyYAML**: Configuration file parsing\n- **wcwidth**: Unicode width calculation for proper text alignment\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## License\n\nThis project is open source. Please check the repository for license information.\n\n## Credits\n\n- Uses [LrcLib](https://lrclib.net/) for lyrics data\n- Built with Python's curses library for terminal UI\n- MPRIS2 integration for media player communication","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faakrishtsp%2Flyrics-on-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faakrishtsp%2Flyrics-on-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faakrishtsp%2Flyrics-on-terminal/lists"}