# Suno Aligned Lyrics Timing Data Examples

## Overview
The `/api/gen/{clip_id}/aligned_lyrics` endpoint returns a data structure with timing information for word-level synchronization, but without the actual lyrics text.

## Data Structure
```json
{
  "data": [
    [],                    // Array 0: Empty (where lyrics text would go)
    [timing_values...],    // Array 1: Duration in seconds for each word/segment
    confidence_score       // Value 2: Confidence score (usually ~1.0)
  ]
}
```

## Example 1: Base Audio Clip
**Clip ID**: `755a1dc6-29a3-4c8b-b2b8-3b09e6d41831`
- **Total segments**: 145
- **Total duration**: 8.09 seconds
- **Confidence**: 1.0

### First 20 timing values (in seconds):
```json
[
  0.19839,   // Word 1: ~0.20s duration
  0.15202,   // Word 2: ~0.15s duration
  0.12479,   // Word 3: ~0.12s duration
  0.15035,   // Word 4: ~0.15s duration
  0.15063,   // Word 5: ~0.15s duration
  0.14022,   // Word 6: ~0.14s duration
  0.13092,   // Word 7: ~0.13s duration
  0.13743,   // Word 8: ~0.14s duration
  0.14969,   // Word 9: ~0.15s duration
  0.14444,   // Word 10: ~0.15s duration
  0.14159,
  0.14022,
  0.14159,
  0.13862,
  0.14161,
  0.13862,
  0.14022,
  0.13862,
  0.13862,
  0.14301
]
```

### Cumulative timestamps (first 10 words):
- Word 1 starts at: 0.00s, ends at: 0.20s
- Word 2 starts at: 0.20s, ends at: 0.35s
- Word 3 starts at: 0.35s, ends at: 0.48s
- Word 4 starts at: 0.48s, ends at: 0.63s
- Word 5 starts at: 0.63s, ends at: 0.78s
- Word 6 starts at: 0.78s, ends at: 0.92s
- Word 7 starts at: 0.92s, ends at: 1.05s
- Word 8 starts at: 1.05s, ends at: 1.19s
- Word 9 starts at: 1.19s, ends at: 1.34s
- Word 10 starts at: 1.34s, ends at: 1.49s

## Example 2: Italo Remix
**Clip ID**: `81e490b9-0935-4b0e-92b6-98da6211cd53`
- **Total segments**: 412
- **Total duration**: 68.52 seconds
- **Confidence**: 0.986

### First 20 timing values (in seconds):
```json
[
  0.27137,   // Longer first word/segment
  0.07838,   // Short segment
  0.18929,   
  0.09900,
  0.22261,
  0.08191,
  0.18923,
  0.08418,
  0.21839,
  0.09051,
  0.19199,
  0.08611,
  0.22027,
  0.08263,
  0.19180,
  0.09238,
  0.21850,
  0.08577,
  0.18747,
  0.09444
]
```

## Example 3: Soft Rock Remix (Longest)
**Clip ID**: `5d75c4fe-f655-4d0f-aeb7-35e07fe967c9`
- **Total segments**: 1323
- **Total duration**: 235.30 seconds (~3.9 minutes)
- **Confidence**: 1.0

This represents a full-length song with 1323 word/segment timings.

## How to Use This Data

To align lyrics with audio, you would:

1. Get the lyrics text (from another endpoint or source)
2. Split the lyrics into words/segments
3. Match each word with its corresponding timing value
4. Use cumulative sum to get start/end timestamps

### Example Python code:
```python
# Assuming you have lyrics and timing data
lyrics_words = ["The", "moon's", "a", "spotlight", ...]  # From lyrics source
timing_data = [0.19839, 0.15202, 0.12479, ...]          # From aligned_lyrics endpoint

# Create word-level timestamps
timestamps = []
current_time = 0

for i, (word, duration) in enumerate(zip(lyrics_words, timing_data)):
    timestamps.append({
        "word": word,
        "start": current_time,
        "end": current_time + duration,
        "duration": duration
    })
    current_time += duration

# Result: Each word with precise start/end times for synchronization
```


## Lyrics Analysis Results

After checking all available endpoints, here are the findings:

### Base Audio (755a1dc6-29a3-4c8b-b2b8-3b09e6d41831)
**Lyrics Found:** No - This is an instrumental track

### Italo (81e490b9-0935-4b0e-92b6-98da6211cd53)
**Lyrics Found:** No - This is an instrumental track

### Soft Rock (5d75c4fe-f655-4d0f-aeb7-35e07fe967c9)
**Lyrics Found:** No - This is an instrumental track

### Summary
All three clips appear to be instrumental covers with `has_vocal: false` in their metadata. The timing data is available but there are no lyrics to align since these are instrumental tracks. For tracks with vocals, the lyrics would appear in the first array of the aligned_lyrics response, paired with the timing durations in the second array.

## Important Notes

1. The timing data is ready and precise to milliseconds
2. The lyrics text needs to be obtained separately
3. These examples are from instrumental covers (`has_vocal: false`), so there may not be actual lyrics
4. The number of timing segments should match the number of words in the lyrics
5. Confidence scores close to 1.0 indicate reliable timing data

## Investigation Update: Why Website Shows Lyrics

After extensive investigation, we discovered why these clips appear to have no lyrics in the API:

1. **All three clips are "Woodwinds" stem generations** - They are instrumental extractions from a parent clip
2. **Task type is "gen_stem"** - This specifically generates instrumental stems without vocals
3. **has_vocal: false** - Confirms these are instrumental tracks
4. **The parent clip (1a0d5e89-f728-4174-a250-819af7d472e4) also has no lyrics**

### Why the website might show "lyrics":
- The website may display the stem type ("Woodwinds") or other metadata as placeholder text
- The website might have a different UI that shows generation parameters instead of actual lyrics
- These are instrumental stems, so any "lyrics" shown would be descriptive text, not actual song lyrics

### Key Finding:
The timing data in the aligned_lyrics endpoint is still valuable - it provides precise timing for audio segments, even in instrumental tracks. For tracks with actual vocals, the lyrics would appear in the first array paired with these timing values.

## Update from Slack

Based on the Slack conversation, for proper remix/cover generation, you need to use:

```json
{
  "task": "cover",
  "cover_clip_id": "your-uploaded-clip-id",
  "metadata": {
    "control_sliders": {
      "audio_weight": 0.26,      // How much original audio influences (0-1)
      "style_weight": 0.54,      // How much style/genre influences (0-1)
      "weirdness_constraint": 0.58  // Creativity level (0-1)
    },
    "is_remix": true
  }
}
```

The `task: "cover"` parameter is crucial for making the API use the uploaded audio as reference.

## Summary: Website Lyrics Mystery Solved

After thorough investigation, we discovered why you see "lyrics" on the website but not in the API:

1. **Your clips are instrumental stems** - All three clips are "Woodwinds" extractions with `task: "gen_stem"`
2. **No actual lyrics exist** - These clips have `has_vocal: false` and empty lyrics arrays
3. **Website likely shows metadata** - The website probably displays stem type, tags, or generation info as descriptive text, not actual lyrics

### For Clips with Real Vocals:

When working with clips that have vocals (`has_vocal: true`), the aligned_lyrics endpoint returns:
- `data[0]`: Array of lyrics words
- `data[1]`: Array of timing durations
- `data[2]`: Confidence score

The empty lyrics arrays in your clips confirm they are purely instrumental, which is expected for stem generations.

## Understanding Timing Segments

Our investigation revealed what these timing segments represent:

### What Are Timing Segments?
- **Musical structure markers** - Each segment represents a musical phrase, beat, or rhythmic pattern
- **Not just for lyrics** - Even instrumental tracks have timing data for their musical elements
- **Audio analysis output** - Suno analyzes the audio to detect changes in rhythm, melody, or energy

### Key Findings:
1. **Different segment patterns** - Each clip has unique segmentation based on its musical style
2. **Beat-aligned timing** - Many segments align with common BPM patterns (120-140 BPM range)
3. **Not direct stem relationships** - The "stems" are actually separate generations with different durations

### Practical Applications:

1. **Video Editing**
   - Use segment boundaries as natural cut points
   - Align video transitions to musical phrases

2. **Music Visualization**
   - Trigger visual effects on longer segments (musical emphasis)
   - Create beat-synchronized animations

3. **Remix Alignment**
   - Match segments between different versions
   - Synchronize multiple tracks using timing data

4. **Placeholder Lyrics**
   - Generate rhythmic text for instrumental tracks
   - Create karaoke-style displays even without vocals

5. **Beat Detection**
   - Identify segments that align with musical beats
   - Calculate effective BPM from segment patterns

### Example Segment Data:
```
Base audio (8s): 145 segments, avg 0.056s each
- Many very short segments (0.000s) suggesting rapid changes
- Longer segments (0.15-0.20s) mark phrase boundaries

Italo remix (68s): 412 segments, avg 0.166s each  
- Consistent 0.19-0.20s segments (eighth notes at ~150 BPM)
- Pattern suggests electronic/dance music structure

Soft rock (235s): 1323 segments, avg 0.178s each
- 0.21-0.23s common durations (eighth notes at ~130-140 BPM)
- Longer track with more varied segment patterns
```

The timing segments provide a powerful tool for audio-visual synchronization, even when lyrics aren't present!