Get Timestamped Lyrics

​

Track Identification

​

Audio ID (Preferred)

• Direct Identification: Use the specific audioId from your generation results
• Higher Priority: Takes precedence if both audioId and musicIndex are provided
• Most Accurate: Ensures you get lyrics for the exact track you want

​

Music Index (Alternative)

• Index-Based: Use 0 for the first track, 1 for the second track
• Fallback Option: Used when audioId is not provided or not found
• Simple Selection: Easy way to choose between the two generated tracks

​

Response Data Structure

​

Aligned Words Array

• Word: The actual lyric text (including formatting like [Verse])
• Success: Boolean indicating if alignment was successful
• Start Time: Precise start timestamp in seconds
• End Time: When the word/phrase ends in seconds
• Alignment Quality: Technical parameter for alignment accuracy

​

Waveform Data

• Visualization Support: Array of amplitude values for creating waveform displays
• Synchronized Graphics: Perfect for building audio visualization components
• Real-time Display: Use with timing data for dynamic visual effects

​

Quality Metrics

• Alignment Score: Accuracy rating for the lyric synchronization
• Stream Status: Whether the audio is streaming or static
• Success Flags: Individual word alignment success indicators

​

Implementation Examples

​

Basic Lyrics Display

function displayLyrics(alignedWords, currentTime) {
  const currentWord = alignedWords.find(word =>
    currentTime >= word.startS && currentTime <= word.endS
  );

  if (currentWord && currentWord.success) {
    highlightWord(currentWord.word);
  }
}

​

Karaoke-Style Synchronization

function updateKaraoke(alignedWords, audioCurrentTime) {
  alignedWords.forEach(word => {
    const element = document.getElementById(`word-${word.id}`);

    if (audioCurrentTime >= word.startS && audioCurrentTime <= word.endS) {
      element.classList.add('singing');
    } else if (audioCurrentTime > word.endS) {
      element.classList.add('sung');
    } else {
      element.classList.remove('singing', 'sung');
    }
  });
}

​

Use Cases

​

Music Applications

• Karaoke Players: Highlight lyrics in real-time during playback
• Music Learning: Help users learn timing and phrasing
• Accessibility: Provide visual cues for hearing-impaired users

​

Content Creation

• Video Subtitles: Generate perfectly timed captions for music videos
• Lyric Videos: Create professional lyric display videos
• Educational Content: Build music theory and timing exercises

​

Interactive Experiences

• Sing-Along Features: Enable users to follow along with precision
• Performance Analysis: Compare user singing to original timing
• Creative Tools: Build rhythm and timing visualization applications

​

Best Practices

​

Timing Accuracy

• Buffer Time: Add small buffers before/after word timing for smooth display
• Validation: Check the success flag before displaying each word
• Fallback: Have backup display logic for unsuccessfully aligned words

​

Performance Optimization

• Preload: Cache timestamped data before playback starts
• Efficient Updates: Only update display when timing changes
• Memory Management: Clean up previous highlights to avoid memory leaks

​

User Experience

• Smooth Transitions: Use CSS transitions for highlight changes
• Visual Clarity: Ensure highlighted text is easily readable
• Error Handling: Gracefully handle missing or misaligned lyrics

Authorization: Bearer YOUR_API_KEY