docs: document synced lyrics api

Author: twlite

apps/website/src/data/docs.json

@@ -196,9 +196,9 @@ export const ShowcaseResource: IShowcase = {
             url: 'https://npm.im/discord-player-tidal'
         },
         {
-            name: "discord-player-youtubei", 
-            description: "Discord Player Youtubei is module that uses the Innertube API to extractor your songs providing more stability and better speeds.",
-            url: "https://npm.im/discord-player-youtubei"
+            name: 'discord-player-youtubei',
+            description: 'Discord Player Youtubei is module that uses the Innertube API to extractor your songs providing more stability and better speeds.',
+            url: 'https://npm.im/discord-player-youtubei'
         }
     ])
 };

apps/website/src/data/showcase.ts

@@ -1,6 +1,75 @@
 # Getting Lyrics
 
-How cool would it be if you could get lyrics of the desired song? Well, Discord Player's Lyrics extractor can help you with that. This feature is powered by [node-genius-lyrics](https://npm.im/genius-lyrics) library.
+Discord Player provides two different methods for getting lyrics of a song. The first method is more robust and also provides synced lyrics. The second method is the old method and is powered by [node-genius-lyrics](https://npm.im/genius-lyrics) library.
+
+## New Method
+
+This method is built into discord-player itself and provides both plaintext and synced lyrics. This method is more robust and reliable than the old method. It is powered by [lrclib](https://liclib.net).
+
+#### Plain Lyrics
+
+```js
+const lyrics = await player.lyrics.search({
+    q: 'alan walker faded'
+}); // this is a lot better than genius but sometimes gives weird result, specify artistName as well in such situations
+
+if (!lyrics.length) return interaction.followUp({ content: 'No lyrics found', ephemeral: true });
+
+const trimmedLyrics = lyrics[0].plainLyrics.substring(0, 1997);
+
+const embed = new EmbedBuilder()
+    .setTitle(lyrics[0].title)
+    .setURL(lyrics[0].url)
+    .setThumbnail(lyrics[0].thumbnail)
+    .setAuthor({
+        name: lyrics[0].artist.name,
+        iconURL: lyrics[0].artist.image,
+        url: lyrics[0].artist.url
+    })
+    .setDescription(trimmedLyrics.length === 1997 ? `${trimmedLyrics}...` : trimmedLyrics)
+    .setColor('Yellow');
+
+return interaction.followUp({ embeds: [embed] });
+```
+
+#### Synced Lyrics
+
+```js
+const results = await player.lyrics.search({
+    q: 'alan walker faded'
+}); // this is a lot better than genius but sometimes gives weird result, specify artistName as well in such situations
+
+const first = results[0];
+
+if (!first.syncedLyrics) {
+    return; // no synced lyrics available
+}
+
+// load raw lyrics to the queue
+const syncedLyrics = queue.syncedLyrics(lyrics);
+
+syncedLyrics.at(timestampInMilliseconds); // manually get a line at a specific timestamp
+
+// Listen to live updates. This will be called whenever discord-player detects a new line in the lyrics
+syncedLyrics.onChange(async (lyrics, timestamp) => {
+    // timestamp = timestamp in lyrics (not queue's time)
+    // lyrics = line in that timestamp
+    console.log(timestamp, lyrics);
+    await interaction.channel?.send({
+        content: `[${timestamp}]: ${lyrics}`
+    });
+});
+
+const unsubscribe = syncedLyrics.subscribe(); // start watching the queue for live updates. The onChange will not be called unless subscribe() has been called.
+
+unsubscribe(); // stop watching the queue for live updates
+```
+
+**Note:** Discord Player relies on queue's current time to detect the current line in the lyrics. It does not validate if the current track is the same as the track for which lyrics were fetched.
+
+# Old Method
+
+This feature is powered by [node-genius-lyrics](https://npm.im/genius-lyrics) library.
 
 ## Example
 
@@ -29,5 +98,5 @@ const embed = new EmbedBuilder()
 return interaction.followUp({ embeds: [embed] });
 ```
 
-> **Note:**
-> It may not find lyrics when using `track.title` as the search query as they contain other infos than just song title.
+> **Note for old method:**
+> It may not find lyrics when using `track.title` as the search query as they contain other infos than just song title.

apps/website/src/pages/guide/_guides/examples/getting_lyrics.mdx

@@ -36,7 +36,7 @@ export class Track<T = unknown> {
     private __metadata: T | null = null;
     private __reqMetadataFn: () => Promise<T | null>;
     public cleanTitle: string;
-    public live: boolean = false
+    public live: boolean = false;
 
     /**
      * Track constructor
@@ -58,7 +58,7 @@ export class Track<T = unknown> {
         this.__metadata = data.metadata ?? null;
         this.__reqMetadataFn = data.requestMetadata || (() => Promise.resolve<T | null>(null));
         this.cleanTitle = data.cleanTitle ?? Util.cleanTitle(this.title, this.source);
-        this.live = data.live ?? false
+        this.live = data.live ?? false;
     }
 
     /**

packages/discord-player/src/fabric/Track.ts

@@ -218,7 +218,6 @@ export class SoundCloudExtractor extends BaseExtractor<SoundCloudExtractorInit>
     }
 
     public async stream(info: Track) {
-        
         const url = await this.internal.util.streamLink(info.url).catch(Util.noop);
         if (!url) throw new Error('Could not extract stream from this track source');
 
@@ -230,7 +229,7 @@ export class SoundCloudExtractor extends BaseExtractor<SoundCloudExtractorInit>
             return this.stream(track);
         }
 
-        const query = sourceExtractor?.createBridgeQuery(track) ?? `${track.author} - ${track.title}`
+        const query = sourceExtractor?.createBridgeQuery(track) ?? `${track.author} - ${track.title}`;
 
         const info = await this.handle(query, {
             requestedBy: track.requestedBy,