@uimaxbai/am-lyrics

To use the component in React, you must install react and @lit/react. Import the AmLyrics component from @uimaxbai/am-lyrics/react.

Important: You must include the 'use client'; directive at the top of your file if using Next.js App Router.

To sync with an audio element, use requestAnimationFrame or the timeupdate event to update the currentTime prop (in milliseconds).

'use client'; // VERY IMPORTANT!!!

import React, { useState, useCallback, useRef, useEffect } from 'react';
import { AmLyrics } from '@uimaxbai/am-lyrics/react';

export default function App() {
  const [currentTime, setCurrentTime] = useState(0);
  const audioRef = useRef<HTMLAudioElement>(null);

  // Sync audio player time with the component
  useEffect(() => {
    const audio = audioRef.current;
    if (!audio) return;

    let animationFrameId: number;

    const updateCurrentTime = () => {
      setCurrentTime(audio.currentTime * 1000);
      animationFrameId = requestAnimationFrame(updateCurrentTime);
    };

    const handlePlay = () => {
      animationFrameId = requestAnimationFrame(updateCurrentTime);
    };

    const handlePause = () => {
      cancelAnimationFrame(animationFrameId);
    };

    const handleTimeUpdate = () => {
      setCurrentTime(audio.currentTime * 1000);
    };

    audio.addEventListener('play', handlePlay);
    audio.addEventListener('pause', handlePause);
    audio.addEventListener('timeupdate', handleTimeUpdate);

    return () => {
      cancelAnimationFrame(animationFrameId);
      audio.removeEventListener('play', handlePlay);
      audio.removeEventListener('pause', handlePause);
      audio.removeEventListener('timeupdate', handleTimeUpdate);
    };
  }, []);

  const handleLineClick = useCallback((event: Event) => {
    const customEvent = event as CustomEvent<{ timestamp: number }>;
    const audio = audioRef.current;
    if (audio) {
      audio.currentTime = customEvent.detail.timestamp / 1000;
      audio.play();
    }
  }, []);

  return (
    <div>
      <audio ref={audioRef} src="/uptown_funk.flac" controls />
      <AmLyrics
        songTitle="Uptown Funk"
        songArtist="Mark Ronson"
        query="Uptown Funk Mark Ronson"
        currentTime={currentTime}
        onLineClick={handleLineClick}
        autoScroll
        highlightColor='#fff'
      />
    </div>
  );
}

To sync lyrics with a standard HTML <audio> element, listen to the timeupdate event on the audio player and update the currentTime property of the <am-lyrics> component (converting seconds to milliseconds). You can also listen for line-click on the component to seek the audio player.

<audio id="audio-player" src="path/to/your/song.mp3" controls></audio>
<am-lyrics
  song-title="Uptown Funk"
  song-artist="Mark Ronson"
  query="Uptown Funk Mark Ronson"
></am-lyrics>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const amLyrics = document.querySelector('am-lyrics');
    const audioPlayer = document.querySelector('#audio-player');

    if (amLyrics && audioPlayer) {
      // Update lyrics time when audio time updates
      audioPlayer.addEventListener('timeupdate', () => {
        // The component expects time in milliseconds
        amLyrics.currentTime = audioPlayer.currentTime * 1000;
      });

      // Seek audio when a lyric line is clicked
      amLyrics.addEventListener('line-click', e => {
        // The event detail contains the timestamp in milliseconds
        audioPlayer.currentTime = e.detail.timestamp / 1000;
        audioPlayer.play();
      });
    }
  });
</script>

The AmLyrics component manages complex lyric animations using a multi-pass system. It handles both syllable-level animations (like wipes) and word-level animations (like growable, char-rise, or char-drag effects).

Key animation behaviors include:

• Wipe Pass: Uses char-wipe or char-start-wipe animations on individual character spans (span.char) to create a progressive highlight effect.
• Pre-Wipe/Pre-Highlight: To ensure smooth transitions between words, the component can 'arm' a pre-wipe on the next word before the current word finishes, using the pre-highlight class and CSS variables --pre-wipe-duration and --pre-wipe-delay.
• Word Styles: Words can be configured with specific animation styles via CSS classes: growable, char-rise, or char-drag.
• State Management: Syllables transition through several states: pre-highlight $\rightarrow$ highlight $\rightarrow$ finished $\rightarrow$ cleanup.