# Stream Music Timestamps

`GET https://api.vultrinference.com/v1/music/{id}/timestamps/stream`

The words of a song as it renders: the job's `timestamps_stream_url`, there for a song asked for with `timestamps: true` while it is `pending` or `in_progress` on a model that streams (`streaming.progressive: true`). Server-sent events, each a JSON `data` line:

- `line`: one lyric line, `{line, words}`, in the shape of `outputs[].timestamps` `lines[]` and `words[]`, once two timings of the audio so far agree where it starts, both heard it clearly, and every line before it has been sent. Each line is sent once, in order. The song renders faster than it plays, so after the opening lines they arrive ahead of the listener. A song whose words cannot be placed while it renders (a first line no timing hears clearly) sends none, and its timing comes with `done`.
- `done`: `{timestamps}`, the finished song's timing, the `timestamps` its output carries once the job completes. It replaces the lines sent before it, which it may have moved by a fraction of a second, and ends the stream.
- `error`: `{error: {code, message}}`, `code` `timestamps_unavailable`: the lyrics could not be timed, or the song failed or was cancelled. It ends the stream.

A comment (`: ping`) is sent on a quiet stream. A listener who connects late, even just after the job completed, gets every event from the start: the stream is kept for 10 minutes after it ends. If the job is retried after a server failure the stream starts over and a listener partway through is let go; connect again. Following the words costs nothing beyond the song's `timestamps`. Send your API key.

## Path parameters

- `id` (string, required): The music job's ID, `music_` followed by 24 hex characters.

## Query parameters

- `index` (integer): The output, as `outputs[]` will number it. [default 0, at least 0]

## Responses

- `200`: The song's lines as they settle, then its finished timing
- `401`: The API key is missing, unknown or not active. Send it as Authorization: Bearer <key>. (error-payload)
- `404`: Not found, expired, or no output at that index (error-payload)
- `409`: The model does not stream, the song was not asked for with timestamps, or the job finished and its timing stream is no longer kept (its timestamps are in the job) (error-payload)

## Example

```bash
curl https://api.vultrinference.com/v1/music/{id}/timestamps/stream \
  -H "Authorization: Bearer $VULTR_INFERENCE_API_KEY"
```

```python
import os
import requests

response = requests.get(
    "https://api.vultrinference.com/v1/music/{id}/timestamps/stream",
    headers={"Authorization": f"Bearer {os.environ['VULTR_INFERENCE_API_KEY']}"},
)
print(response.status_code)
```

```javascript
const response = await fetch("https://api.vultrinference.com/v1/music/{id}/timestamps/stream", {
  headers: {
    Authorization: `Bearer ${process.env.VULTR_INFERENCE_API_KEY}`,
  },
});
console.log(response.status);
```