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

# Three API Modes

> Choose the right pipeline mode for your workflow

Every transcription job runs in one of three modes, selected by combining the `align` and `review` parameters. The mode determines what output is produced, how long it takes, and how results are delivered.

## Mode comparison

| Mode              | Parameters                   | Output                                                      | Approx. time   | Best for                              |
| ----------------- | ---------------------------- | ----------------------------------------------------------- | -------------- | ------------------------------------- |
| Transcript only   | `align=false`                | Transcript + transliteration + translation + cultural notes | \~60s          | Metadata, liner notes, sync licensing |
| Full pipeline     | `align=true` (default)       | All of above + LRC + SRT + word-level JSON                  | \~90s          | Karaoke, lyric display, DSP delivery  |
| Reviewed delivery | `align=true` + `review=true` | All of above, delivered after artist approval               | \~90s + review | Artist approval workflows             |

***

## Mode 1 — Transcript only

Set `align=false` to skip time-alignment entirely. lyrcs.ai transcribes the audio and returns the lyrics as structured text. No LRC or SRT files are generated.

```json theme={null}
{
  "audio_url": "https://cdn.example.com/song.mp3",
  "language": "Hindi",
  "align": false
}
```

**Output fields:**

* `results.transcript` — lyrics in the original script
* `results.transliteration` — phonetic romanisation
* `results.translation` — English translation
* `results.cultural_notes` — contextual notes (may be null)

**What's missing:** `results.downloads` is not present. No LRC or SRT files.

**Use cases:**

* Delivering lyric metadata to streaming stores (Spotify, Apple Music, Amazon)
* Generating liner notes for releases
* Populating sync licensing databases with searchable lyrics
* Any workflow where timing is not needed

***

## Mode 2 — Full pipeline

The default. Transcription runs first, then alignment maps each lyric line to a timestamp in the audio.

```json theme={null}
{
  "audio_url": "https://cdn.example.com/song.mp3",
  "language": "Tamil"
}
```

**Output fields:**

* Everything from Mode 1, plus:
* `results.downloads.lrc_original` — time-synced LRC in original script
* `results.downloads.lrc_transliterated` — time-synced LRC in romanised form
* `results.downloads.srt_original` — SRT in original script
* `results.downloads.srt_transliterated` — SRT in romanised form
* `results.downloads.words_original` — per-word timestamps in original script (JSON)
* `results.downloads.words_transliterated` — per-word timestamps in romanised form (JSON)

Word-level JSON is included by default with all aligned jobs (`word_align=true`). Set `word_align=false` to skip it and receive only LRC and SRT.

**Use cases:**

* Karaoke and sing-along applications
* Lyric display synced to audio playback on streaming platforms
* Subtitle tracks for music videos
* Live lyric scrolling on DSPs

***

## Mode 3 — Reviewed delivery

Adds an artist approval gate. After alignment completes, results are held and a `job.awaiting_review` webhook fires with a `review_url`. The `job.complete` webhook fires — with full results — only after the artist approves.

```json theme={null}
{
  "audio_url": "https://cdn.example.com/song.mp3",
  "language": "Punjabi",
  "review": true,
  "webhook_url": "https://api.example.com/webhooks/lyrcs"
}
```

**Delivery sequence:**

1. Transcription + alignment completes (\~90s)
2. `job.awaiting_review` fires → contains `review_url`
3. Distributor forwards `review_url` to artist
4. Artist approves in lyrcs.ai Studio
5. `job.complete` fires → full results + downloads

**Use cases:**

* Artist approval required before public lyric delivery
* Quality control for high-profile releases
* Markets where lyrics are legally sensitive and must be approved by rights holders

***

## Decision guide

```
Do you need time-synced lyrics (LRC/SRT)?
├── No  → align=false (Mode 1, ~60s, faster)
└── Yes → Does the artist need to approve before delivery?
           ├── No  → align=true (Mode 2, default, ~90s)
           └── Yes → align=true + review=true (Mode 3, ~90s + review time)
```

<Note>
  `review=true` requires a `webhook_url` to be useful — without it, there's no way to receive the `review_url` and no way to know when approval happens.
</Note>