starred/koel-koel

Fork 0

mirror of https://github.com/koel/koel.git synced 2026-04-25 16:56:02 +03:00

[PR #2153] [CLOSED] feat: add synchronized LRC lyrics support #2113

New issue

Closed

opened 2026-02-26 03:33:18 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 03:33:18 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/koel/koel/pull/2153
Author: @DzmingLi
Created: 10/25/2025
Status: ❌ Closed

Base: master ← Head: master

📝 Commits (3)

33bf1bb chore: add Nix flake for development environment
b553e56 fix: preserve LRC timestamps in lyrics
760fa80 feat: add synchronized lyrics display with LRC support

📊 Changes

5 files changed (+673 additions, -5 deletions)

View changed files

📝 app/Casts/SongLyricsCast.php (+2 -2)
📝 app/Services/Scanners/Scanner.php (+44 -1)
➕ flake.lock (+61 -0)
➕ flake.nix (+440 -0)
📝 resources/assets/js/components/ui/LyricsPane.vue (+126 -2)

📄 Description

Description

This PR adds support for synchronized LRC lyrics with real-time highlighting and auto-scrolling. When a song has LRC-formatted lyrics with timestamps, the lyrics pane will automatically synchronize with playback, highlighting the current line and scrolling to keep it centered.

Motivation

Koel already supports reading LRC files (#1447, #1502) but displays them as plain text without synchronization. This enhancement provides a karaoke-style lyrics experience that improves the music listening experience, especially for users who enjoy following along with lyrics.

Checklist

I've tested my changes thoroughly and added tests where applicable
I've updated relevant documentation (if any)
My code follows the project's conventions

Technical Details

Backend Changes

SongLyricsCast: Modified to preserve LRC timestamps instead of stripping them from the database

Frontend Changes

LyricsPane.vue:
- Parse LRC format with regex /\[(\d{2}):(\d{2})\.(\d{2,3})\](.*)/g
- Monitor playback position every 100ms
- Automatically scroll to keep current line centered
- Apply visual highlighting to active line
- Graceful fallback to plain text for non-LRC lyrics

Compatibility

Fully backward compatible with existing plain text lyrics
No database migrations required
Works with existing LRC files in the music library
Scanner already supports detecting LRC file changes (from #1502)

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/koel/koel/pull/2153 **Author:** [@DzmingLi](https://github.com/DzmingLi) **Created:** 10/25/2025 **Status:** ❌ Closed **Base:** `master` ← **Head:** `master` --- ### 📝 Commits (3) - [`33bf1bb`](https://github.com/koel/koel/commit/33bf1bb5ead7d68192653066a6230cd7c659bf97) chore: add Nix flake for development environment - [`b553e56`](https://github.com/koel/koel/commit/b553e5670d8f1f06995cdd093191bb96688e70e4) fix: preserve LRC timestamps in lyrics - [`760fa80`](https://github.com/koel/koel/commit/760fa80ceb822128458cc33499488ddbae4be533) feat: add synchronized lyrics display with LRC support ### 📊 Changes **5 files changed** (+673 additions, -5 deletions) <details> <summary>View changed files</summary> 📝 `app/Casts/SongLyricsCast.php` (+2 -2) 📝 `app/Services/Scanners/Scanner.php` (+44 -1) ➕ `flake.lock` (+61 -0) ➕ `flake.nix` (+440 -0) 📝 `resources/assets/js/components/ui/LyricsPane.vue` (+126 -2) </details> ### 📄 Description ## Description This PR adds support for synchronized LRC lyrics with real-time highlighting and auto-scrolling. When a song has LRC-formatted lyrics with timestamps, the lyrics pane will automatically synchronize with playback, highlighting the current line and scrolling to keep it centered. ## Motivation Koel already supports reading LRC files (#1447, #1502) but displays them as plain text without synchronization. This enhancement provides a karaoke-style lyrics experience that improves the music listening experience, especially for users who enjoy following along with lyrics. ## Checklist - [x] I've tested my changes thoroughly and added tests where applicable - [x] I've updated relevant documentation (if any) - [x] My code follows the project's conventions ## Technical Details ### Backend Changes - **SongLyricsCast**: Modified to preserve LRC timestamps instead of stripping them from the database ### Frontend Changes - **LyricsPane.vue**: - Parse LRC format with regex `/\[(\d{2}):(\d{2})\.(\d{2,3})\](.*)/g` - Monitor playback position every 100ms - Automatically scroll to keep current line centered - Apply visual highlighting to active line - Graceful fallback to plain text for non-LRC lyrics ### Compatibility - Fully backward compatible with existing plain text lyrics - No database migrations required - Works with existing LRC files in the music library - Scanner already supports detecting LRC file changes (from #1502) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

kerem

2026-02-26 03:33:18 +03:00

closed this issue
added the
pull-request
label

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/koel-koel#2113

No description provided.

Rows
Columns