From 82a561b87d3b6d023168d4604c1030ff936f55f4 Mon Sep 17 00:00:00 2001
From: Alex <48403821+AlexDalas@users.noreply.github.com>
Date: Tue, 8 Apr 2025 00:59:18 +1000
Subject: Add API support for ELRC word-based lyrics (#12941)

* Add API support for ELRC word-based lyrics

Adds support for word-based timestamps from within ELRC files.

* Create TimeTags object

* redo TimeTag implementation

Change TimeTag to long, redo TimeTag implementation
Make timestamp not nullable
Update MediaBrowser.Model/Lyrics/LyricLine.cs
Make TimeTag list IReadOnlyList
Remove nullable Timestamp
Update TimeTag description

Co-Authored-By: Cody Robibero <cody@robibe.ro>

* Changes to LyricLineTimeTag

Moved TimeTag to LyricLineTimeTag
Change "timestamp" to "start" for consistency
Change plural "TimeTags" to "Cues"
Change comments

* Change LyricLineTimeTag to LyricLineCue, include info about end times

* Remove width

* Remove width tag

* Rewrite cue parser and add tests

---------

Co-authored-by: Cody Robibero <cody@robibe.ro>
---
 MediaBrowser.Model/Lyrics/LyricLine.cs    | 11 +++++++++-
 MediaBrowser.Model/Lyrics/LyricLineCue.cs | 35 +++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 MediaBrowser.Model/Lyrics/LyricLineCue.cs

(limited to 'MediaBrowser.Model')

diff --git a/MediaBrowser.Model/Lyrics/LyricLine.cs b/MediaBrowser.Model/Lyrics/LyricLine.cs
index 64d1f64c2..788bace69 100644
--- a/MediaBrowser.Model/Lyrics/LyricLine.cs
+++ b/MediaBrowser.Model/Lyrics/LyricLine.cs
@@ -1,3 +1,5 @@
+using System.Collections.Generic;
+
 namespace MediaBrowser.Model.Lyrics;
 
 /// <summary>
@@ -10,10 +12,12 @@ public class LyricLine
     /// </summary>
     /// <param name="text">The lyric text.</param>
     /// <param name="start">The lyric start time in ticks.</param>
-    public LyricLine(string text, long? start = null)
+    /// <param name="cues">The time-aligned cues for the song's lyrics.</param>
+    public LyricLine(string text, long? start = null, IReadOnlyList<LyricLineCue>? cues = null)
     {
         Text = text;
         Start = start;
+        Cues = cues;
     }
 
     /// <summary>
@@ -25,4 +29,9 @@ public class LyricLine
     /// Gets the start time in ticks.
     /// </summary>
     public long? Start { get; }
+
+    /// <summary>
+    /// Gets the time-aligned cues for the song's lyrics.
+    /// </summary>
+    public IReadOnlyList<LyricLineCue>? Cues { get; }
 }
diff --git a/MediaBrowser.Model/Lyrics/LyricLineCue.cs b/MediaBrowser.Model/Lyrics/LyricLineCue.cs
new file mode 100644
index 000000000..1172a0231
--- /dev/null
+++ b/MediaBrowser.Model/Lyrics/LyricLineCue.cs
@@ -0,0 +1,35 @@
+namespace MediaBrowser.Model.Lyrics;
+
+/// <summary>
+/// LyricLineCue model, holds information about the timing of words within a LyricLine.
+/// </summary>
+public class LyricLineCue
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="LyricLineCue"/> class.
+    /// </summary>
+    /// <param name="position">The start of the character index of the lyric.</param>
+    /// <param name="start">The start of the timestamp the lyric is synced to in ticks.</param>
+    /// <param name="end">The end of the timestamp the lyric is synced to in ticks.</param>
+    public LyricLineCue(int position, long start, long? end)
+    {
+        Position = position;
+        Start = start;
+        End = end;
+    }
+
+    /// <summary>
+    /// Gets the character index of the lyric.
+    /// </summary>
+    public int Position { get; }
+
+    /// <summary>
+    /// Gets the timestamp the lyric is synced to in ticks.
+    /// </summary>
+    public long Start { get; }
+
+    /// <summary>
+    /// Gets the end timestamp the lyric is synced to in ticks.
+    /// </summary>
+    public long? End { get; }
+}
-- 
cgit v1.2.3