@uimaxbai/am-lyrics 0.5.0 → 0.5.1

package/README.md

@@ -18,9 +18,11 @@ Or, just use the CDN.
 </script>
 
 <am-lyrics
-  query="Uptown Funk"
-  music-id=""
-  isrc=""
+  song-title="Uptown Funk"
+  song-artist="Mark Ronson"
+  song-album="Uptown Special"
+  song-duration="269000"
+  query="Uptown Funk Mark Ronson"
   current-time="0"
   duration=""
   highlight-color="#f00"
@@ -36,11 +38,15 @@ Or, just use the CDN.
 
 | Property/Attribute | Type | Default | Description |
 |-------------------|------|---------|-------------|
-| `query` | `string` | `undefined` | Search query for Apple Music song |
-| `music-id` | `string` | `undefined` | Specific Apple Music song ID (rarely used) |
+| `query` | `string` | `undefined` | Search phrase that resolves metadata via LyricsPlus catalog (falls back to Apple Music search) |
+| `music-id` | `string` | `undefined` | Specific Apple Music song ID (served through the backup Apple endpoint) |
 | `isrc` | `string` | `undefined` | ISRC code to verify correct song match |
+| `song-title` | `string` | `undefined` | Preferred title for LyricsPlus (primary) provider |
+| `song-artist` | `string` | `undefined` | Preferred artist name for LyricsPlus provider |
+| `song-album` | `string` | `undefined` | Optional album name passed to LyricsPlus provider |
+| `song-duration` | `number` | `undefined` | Optional song duration in milliseconds sent to LyricsPlus |
 | `current-time` | `number` | `0` | Current playback time in milliseconds |
-| `duration` | `number` | `undefined` | Song duration in milliseconds. **Set to `-1` to reset/stop playback** |
+| `duration` | `number` | `undefined` | Playback timer duration in milliseconds. **Set to `-1` to reset/stop playback** |
 | `highlight-color` | `string` | `"#000"` | Color for highlighted/active lyrics |
 | `hover-background-color` | `string` | `"#f0f0f0"` | Background color on line hover |
 | `hide-source-footer` | `boolean` | `false` | Hide/show the source attribution footer |
@@ -68,6 +74,15 @@ am-lyrics {
 **Note**: The CSS variables take precedent over the set properties above.
 
 
+## Lyrics providers
+
+The component now favours the LyricsPlus (KPoe) API that powers [YouLyPlus](https://github.com/ibratabian17/YouLyPlus).
+
+1. Provide `song-title` and `song-artist` (plus optional `song-album`/`song-duration`) to request word-synced lyrics from LyricsPlus. A standalone `query` such as `"Bad Habit - Steve Lacy"` also works—the component looks up the metadata through LyricsPlus' `/v1/songlist/search` endpoint.
+2. If LyricsPlus cannot serve lyrics or metadata is missing, the component automatically falls back to the legacy Apple Music endpoint using the best available identifiers (`query`, `music-id`, `isrc`). Requests that rely solely on `music-id` are handled exclusively by this backup service because LyricsPlus does not support Apple IDs.
+
+The footer shows the active provider (e.g. “LyricsPlus (KPoe)” or “Apple Music”) so you always know which service responded. Supplying both metadata *and* a `query` gives the best results because the query remains available for the Apple Music backup.
+
 
 ## Events
 
@@ -151,7 +166,9 @@ export default function App() {
     <div>
       <audio ref={audioRef} src="/uptown_funk.flac" controls />
         <AmLyrics
-          query="Uptown Funk"
+          songTitle="Uptown Funk"
+          songArtist="Mark Ronson"
+          query="Uptown Funk Mark Ronson"
           currentTime={currentTime}
           onLineClick={handleLineClick}
           autoScroll
@@ -218,7 +235,15 @@ The timer needs to be defined by yourself. For example:
     const searchInput = document.querySelector('#search-input');
     const amLyrics = document.querySelector('am-lyrics');
     if (searchInput && amLyrics) {
-      amLyrics.query = searchInput.value;
+      // Expect "Title - Artist" in the search field for optimal LyricsPlus results
+      const userInput = searchInput.value.trim();
+      const [titlePart = '', artistPart = ''] = userInput
+        .split(' - ')
+        .map(part => part.trim());
+
+      amLyrics.songTitle = titlePart || userInput;
+      amLyrics.songArtist = artistPart;
+      amLyrics.query = userInput;
       amLyrics.isrc = '';
       amLyrics.musicId = '';
     }
@@ -250,7 +275,11 @@ You can synchronize the lyrics with an HTML `<audio>` element.
 
 ```html
 <audio id="audio-player" src="path/to/your/song.mp3" controls></audio>
-<am-lyrics query="Uptown Funk"></am-lyrics>
+<am-lyrics
+  song-title="Uptown Funk"
+  song-artist="Mark Ronson"
+  query="Uptown Funk Mark Ronson"
+></am-lyrics>
 
 <script>
   document.addEventListener('DOMContentLoaded', () => {

package/demo/index.html

@@ -17,15 +17,21 @@
 </head>
 <body>
   <div>
-    <input id="search-input" type="text" placeholder="Search for a song" />
-    <button id="search-button">Search</button>
+    <input id="title-input" type="text" placeholder="Song title" />
+    <input id="artist-input" type="text" placeholder="Artist" />
+    <input id="query-input" type="text" placeholder="Search query (e.g. Title - Artist)" />
+    <input id="duration-input" type="number" placeholder="Duration (ms)" />
+    <button id="load-button">Load lyrics</button>
   </div>
 
   <am-lyrics
-    query="Uptown Funk"
+    song-title="Uptown Funk"
+    song-artist="Mark Ronson"
+    song-album="Uptown Special"
+    song-duration="269000"
+    query="Uptown Funk Mark Ronson"
     music-id=""
     isrc=""
-    duration=""
     highlight-color="#f00"
     hover-background-color="#e0e0e0"
     hide-source-footer="true"
@@ -35,10 +41,14 @@
   ></am-lyrics>
   <!--
   <am-lyrics
-    query="Uptown Funk"               // Search Apple Music for a song
+    song-title="Uptown Funk"          // Preferred: provide title for LyricsPlus API
+    song-artist="Mark Ronson"         // Preferred: provide artist for LyricsPlus API
+    song-album="Uptown Special"       // Optional album metadata sent to LyricsPlus
+    song-duration="269000"            // Optional song duration (ms) sent to LyricsPlus
+    query="Uptown Funk Mark Ronson"   // Fallback search string for Apple Music backup API
     music-id=""                       // Use this if you have a specific song ID from Apple Music (almost never)
     isrc=""                           // To be used WITH a query, just to double check if it is correct
-    duration=""                       // Duration of your timer (the component takes it in and syncs to the words. See JS below)
+    duration=""                       // Playback timer duration (component sync). See JS below
     highlight-color="#000"            // Color of the highlighted words
     hover-background-color="#f0f0f0"  // Color of the line when you hover over it
     hide-source-footer="false"        // Controls whether the footer at the bottom is a larger one or a more compact GitHub link.
@@ -90,14 +100,44 @@
       animate();
     }
 
-    function handleSearch() {
-      const searchInput = document.querySelector('#search-input');
+    function handleLoadMetadata() {
+      const titleInput = document.querySelector('#title-input');
+      const artistInput = document.querySelector('#artist-input');
+      const durationInput = document.querySelector('#duration-input');
+      const queryInput = document.querySelector('#query-input');
       const amLyrics = document.querySelector('am-lyrics');
-      if (searchInput && amLyrics) {
-        amLyrics.query = searchInput.value;
-        amLyrics.isrc = '';
-        amLyrics.musicId = '';
+
+      if (!amLyrics) return;
+
+      const title = titleInput?.value.trim() ?? '';
+      const artist = artistInput?.value.trim() ?? '';
+      const queryText = queryInput?.value.trim() ?? '';
+      const durationText = durationInput?.value.trim() ?? '';
+      const durationMs = durationText ? Number(durationText) : NaN;
+
+      if (titleInput) {
+        amLyrics.songTitle = title;
+      }
+
+      if (artistInput) {
+        amLyrics.songArtist = artist;
+      }
+
+      if (!Number.isNaN(durationMs) && durationMs > 0) {
+        amLyrics.songDurationMs = durationMs;
+      } else if (durationText === '') {
+        amLyrics.songDurationMs = undefined;
+      }
+
+      const fallbackQuery = queryText || [title, artist].filter(Boolean).join(' ');
+      if (fallbackQuery) {
+        amLyrics.query = fallbackQuery;
+      } else {
+        amLyrics.query = '';
       }
+
+      amLyrics.isrc = '';
+      amLyrics.musicId = '';
     }
 
     function resetPlayback() {
@@ -112,16 +152,36 @@
 
     document.addEventListener('DOMContentLoaded', () => {
       const amLyrics = document.querySelector('am-lyrics');
-      const searchButton = document.querySelector('#search-button');
+      const loadButton = document.querySelector('#load-button');
       const startButton = document.querySelector('#start-button');
       const resetButton = document.querySelector('#reset-button');
+      const titleInput = document.querySelector('#title-input');
+      const artistInput = document.querySelector('#artist-input');
+      const queryInput = document.querySelector('#query-input');
+      const durationInput = document.querySelector('#duration-input');
 
       if (amLyrics) {
         amLyrics.addEventListener('line-click', handleLineClick);
       }
 
-      if (searchButton) {
-        searchButton.addEventListener('click', handleSearch);
+      if (titleInput && amLyrics?.songTitle) {
+        titleInput.value = amLyrics.songTitle;
+      }
+
+      if (artistInput && amLyrics?.songArtist) {
+        artistInput.value = amLyrics.songArtist;
+      }
+
+      if (queryInput && amLyrics?.query) {
+        queryInput.value = amLyrics.query;
+      }
+
+      if (durationInput && typeof amLyrics?.songDurationMs === 'number') {
+        durationInput.value = String(amLyrics.songDurationMs);
+      }
+
+      if (loadButton) {
+        loadButton.addEventListener('click', handleLoadMetadata);
       }
 
       if (startButton) {

package/dist/src/AmLyrics.d.ts

@@ -4,6 +4,10 @@ export declare class AmLyrics extends LitElement {
     query?: string;
     musicId?: string;
     isrc?: string;
+    songTitle?: string;
+    songArtist?: string;
+    songAlbum?: string;
+    songDurationMs?: number;
     highlightColor: string;
     hoverBackgroundColor: string;
     hideSourceFooter: boolean;
@@ -19,6 +23,7 @@ export declare class AmLyrics extends LitElement {
     private activeBackgroundWordIndices;
     private mainWordProgress;
     private backgroundWordProgress;
+    private lyricsSource;
     private animationFrameId?;
     private mainWordAnimations;
     private backgroundWordAnimations;
@@ -30,6 +35,19 @@ export declare class AmLyrics extends LitElement {
     connectedCallback(): void;
     disconnectedCallback(): void;
     private fetchLyrics;
+    private onLyricsLoaded;
+    private resolveSongMetadata;
+    private searchAppleMusic;
+    private static parseQueryMetadata;
+    private static searchLyricsPlusCatalog;
+    private static fetchLyricsFromYouLyPlus;
+    private fetchLyricsFromApple;
+    private static convertKPoeLyrics;
+    private static ensureAppleWordSpacing;
+    private static applySpacingToSyllables;
+    private static startsWithPunctuation;
+    private static endsWithNoSpaceMarker;
+    private static toMilliseconds;
     firstUpdated(): void;
     updated(changedProperties: Map<string | number | symbol, unknown>): void;
     private static arraysEqual;

package/dist/src/AmLyrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AmLyrics.d.ts","sourceRoot":"","sources":["../../src/AmLyrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,UAAU,EAAE,MAAM,KAAK,CAAC;AA4B5C,qBAAa,QAAS,SAAQ,UAAU;IACtC,MAAM,CAAC,MAAM,0BA+KX;IAGF,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,IAAI,CAAC,EAAE,MAAM,CAAC;IAGd,cAAc,SAAU;IAGxB,oBAAoB,SAAa;IAGjC,gBAAgB,UAAS;IAGzB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,UAAU,UAAQ;IAGlB,WAAW,UAAQ;IAGnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,WAAW,SAAK;IAGhB,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,MAAM,CAAC,CAAe;IAG9B,OAAO,CAAC,iBAAiB,CAAgB;IAGzC,OAAO,CAAC,qBAAqB,CAAkC;IAG/D,OAAO,CAAC,2BAA2B,CAAkC;IAGrE,OAAO,CAAC,gBAAgB,CAAkC;IAG1D,OAAO,CAAC,sBAAsB,CAAkC;IAEhE,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAElC,OAAO,CAAC,kBAAkB,CAGZ;IAEd,OAAO,CAAC,wBAAwB,CAGlB;IAGd,OAAO,CAAC,eAAe,CAAC,CAAc;IAEtC,OAAO,CAAC,qBAAqB,CAAuB;IAEpD,OAAO,CAAC,mBAAmB,CAAC,CAAS;IAGrC,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,oBAAoB,CAAS;IAErC,iBAAiB;IAKjB,oBAAoB;YAUN,WAAW;IAqDzB,YAAY;IASZ,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAoFjE,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B,OAAO,CAAC,gBAAgB;IA0BxB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,qBAAqB;IAiC7B,OAAO,CAAC,sBAAsB;IA8D9B,OAAO,CAAC,wBAAwB;IAwChC,OAAO,CAAC,eAAe;IA4CvB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,MAAM,CAAC,0BAA0B;IAkBzC,OAAO,CAAC,kBAAkB;IA2C1B,OAAO,CAAC,oBAAoB;IAsC5B,OAAO,CAAC,eAAe;IA4HvB,MAAM;CAwKP"}
+{"version":3,"file":"AmLyrics.d.ts","sourceRoot":"","sources":["../../src/AmLyrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,UAAU,EAAE,MAAM,KAAK,CAAC;AA0E5C,qBAAa,QAAS,SAAQ,UAAU;IACtC,MAAM,CAAC,MAAM,0BAgLX;IAGF,KAAK,CAAC,EAAE,MAAM,CAAC;IAGf,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,IAAI,CAAC,EAAE,MAAM,CAAC;IAGd,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,cAAc,CAAC,EAAE,MAAM,CAAC;IAGxB,cAAc,SAAU;IAGxB,oBAAoB,SAAa;IAGjC,gBAAgB,UAAS;IAGzB,UAAU,CAAC,EAAE,MAAM,CAAC;IAGpB,UAAU,UAAQ;IAGlB,WAAW,UAAQ;IAGnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,WAAW,SAAK;IAGhB,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,MAAM,CAAC,CAAe;IAG9B,OAAO,CAAC,iBAAiB,CAAgB;IAGzC,OAAO,CAAC,qBAAqB,CAAkC;IAG/D,OAAO,CAAC,2BAA2B,CAAkC;IAGrE,OAAO,CAAC,gBAAgB,CAAkC;IAG1D,OAAO,CAAC,sBAAsB,CAAkC;IAGhE,OAAO,CAAC,YAAY,CAAuB;IAE3C,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAElC,OAAO,CAAC,kBAAkB,CAGZ;IAEd,OAAO,CAAC,wBAAwB,CAGlB;IAGd,OAAO,CAAC,eAAe,CAAC,CAAc;IAEtC,OAAO,CAAC,qBAAqB,CAAuB;IAEpD,OAAO,CAAC,mBAAmB,CAAC,CAAS;IAGrC,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,oBAAoB,CAAS;IAErC,iBAAiB;IAKjB,oBAAoB;YAUN,WAAW;IA4DzB,OAAO,CAAC,cAAc;YAkBR,mBAAmB;YA4JnB,gBAAgB;IAwC9B,OAAO,CAAC,MAAM,CAAC,kBAAkB;mBAkCZ,uBAAuB;mBA6CvB,wBAAwB;YAyD/B,oBAAoB;IA8BlC,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAiFhC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAUrC,OAAO,CAAC,MAAM,CAAC,uBAAuB;IA0BtC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAIpC,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAIpC,OAAO,CAAC,MAAM,CAAC,cAAc;IAa7B,YAAY;IAWZ,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAwFjE,OAAO,CAAC,MAAM,CAAC,WAAW;IAI1B,OAAO,CAAC,gBAAgB;IA0BxB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,qBAAqB;IAiC7B,OAAO,CAAC,sBAAsB;IA8D9B,OAAO,CAAC,wBAAwB;IAwChC,OAAO,CAAC,eAAe;IA4CvB,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,MAAM,CAAC,0BAA0B;IAkBzC,OAAO,CAAC,kBAAkB;IA2C1B,OAAO,CAAC,oBAAoB;IAsC5B,OAAO,CAAC,eAAe;IA4HvB,MAAM;CA4KP"}