> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musicmint.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lyrics Timeline

> Get word-level timing data for lyrics synchronized to the audio

## Endpoint

```http theme={null}
GET /api/v1/music/timeline?clip_id={clip_id}
```

**Synchronous.** Returns word-level timing data immediately.

Returns the start and end timestamps for each lyric word in a clip. Use this to build synchronized lyric displays (karaoke-style), subtitle files, or animated text overlays.

## Query parameters

| Parameter | Type   | Required | Description                                                                                                                                              |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clip_id` | string | **Yes**  | Clip ID to retrieve timing for. Obtain from [Upload Audio](/api-reference/music/upload) (`data.clipId`) or a completed generation task (`results[].id`). |

## Response

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "aligned": [
      { "word": "Hello", "start": 2.14, "end": 2.56 },
      { "word": "world", "start": 2.58, "end": 2.99 },
      { "word": "this", "start": 3.1, "end": 3.3 },
      { "word": "is", "start": 3.32, "end": 3.45 },
      { "word": "music", "start": 3.5, "end": 3.95 }
    ]
  }
}
```

| Field             | Type   | Description                  |
| ----------------- | ------ | ---------------------------- |
| `aligned`         | array  | Array of word timing objects |
| `aligned[].word`  | string | The lyric word               |
| `aligned[].start` | float  | Start time in seconds        |
| `aligned[].end`   | float  | End time in seconds          |

## Example

```bash theme={null}
curl "https://api.example.com/api/v1/music/timeline?clip_id=abc123def456" \
  -H "Authorization: Bearer sk-mm-your-key"
```

## Use case: karaoke display

Iterate through `aligned` words, highlight the current word based on the audio playback time:

```javascript theme={null}
function getCurrentWord(aligned, currentTime) {
  return aligned.find(w => currentTime >= w.start && currentTime <= w.end);
}
```