Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/elevenlabs/llms.txt

Use this file to discover all available pages before exploring further.

Forced alignment takes an audio file and its exact transcript text, then returns precise timestamps at both the word and character level. Unlike automatic speech recognition — which transcribes unknown audio — forced alignment assumes you already know exactly what was spoken and instead tells you when each word and character occurs in the recording. This makes it ideal for subtitle generation, karaoke timing, and audio editing workflows where frame-accurate markers are required.

​
Usage

Call create() with a Content::audio() value and the verbatim transcript string. It returns a ForcedAlignmentResult immediately. 
$alignment = ElevenLabs::forcedAlignment()->create(
    Content::audio(__DIR__.'/narration.wav'),
    'The exact transcript spoken in the recording.',
);

foreach ($alignment->words as $word) {
    echo "{$word->text}: {$word->start} - {$word->end}\n";
}
The $text argument must be a verbatim match of what is spoken in the audio. Any discrepancy — an extra word, a contraction written differently, or punctuation that differs from how it was spoken — will increase the loss score and may produce inaccurate timestamps. Prepare your transcript carefully before submitting.

​
Parameters

​
$audio
Content
required
The audio recording to align. Use Content::audio() with a local file path or binary data. The file is uploaded as a multipart form file part with the fixed filename audio.wav and content type audio/wav, regardless of the original filename.
Content::audio(__DIR__.'/narration.wav')
​
$text
string
required
The exact transcript of what is spoken in the audio. Must match the spoken content word-for-word.

​
Return Type

​
ForcedAlignmentResult

​
characters
list<AlignmentItem>
Character-level alignment. Each AlignmentItem represents a single character with its start and end time in the audio.
​
words
list<AlignmentItem>
Word-level alignment. Each AlignmentItem represents a whole word token with its start and end time.
​
loss
float
An alignment quality score for the entire result. Lower values indicate a closer match between the audio and the provided transcript. A high loss score suggests the transcript may not match the audio.
​
rawResponse
array
The full decoded JSON response from the ElevenLabs API for inspection or debugging.

​
AlignmentItem

Each entry in both characters and words is an AlignmentItem.
​
text
string
The character or word token this item represents.
​
start
float
Start time of this token in seconds, measured from the beginning of the audio file.
​
end
float
End time of this token in seconds.
​
loss
float|null
Per-token alignment quality score. Present on word-level items; may be null on character-level items.

​
Working with the Results

​
Word-level timing

Word-level timestamps are useful for subtitle generation and karaoke-style highlighting, where you need to know when each word begins and ends. 
foreach ($alignment->words as $word) {
    printf(
        "%-20s start=%.3fs  end=%.3fs\n",
        $word->text,
        $word->start,
        $word->end,
    );
}

​
Character-level timing

Character-level timestamps let you animate text at the individual letter level — useful for karaoke underlining or precise audio-editing markers. 
foreach ($alignment->characters as $char) {
    // $char->text  — the individual character
    // $char->start — when it starts, in seconds
    // $char->end   — when it ends, in seconds
    echo "'{$char->text}': {$char->start}s – {$char->end}s\n";
}

​
Inspecting alignment quality

The loss property is available at both the result level and on individual word tokens. Use it to detect misaligned segments or to validate that the supplied transcript matches the audio before producing final output. 
if ($alignment->loss > 1.0) {
    echo "Warning: high alignment loss ({$alignment->loss}). Check that the transcript matches the audio.\n";
}

foreach ($alignment->words as $word) {
    if ($word->loss !== null && $word->loss > 0.5) {
        echo "Uncertain alignment for word: '{$word->text}' (loss={$word->loss})\n";
    }
}

​
Typical Use Cases

Subtitle Generation

Convert word-level timestamps directly into SRT or VTT cue times, mapping each word to the exact moment it is spoken.

Karaoke Timing

Drive character- or word-level highlighting in real time by triggering UI updates at the precise start time of each token.

Audio Editing Markers

Import word timestamps as named markers in a DAW or video editor to jump immediately to any word in a long recording.

Build docs developers (and LLMs) love

Get started for freeTalk to us