ElevenLabs Forced Alignment: Turn an Approved Script into Captions

You have a finished voiceover and an approved script. What you need now is timing: where each word actually begins and ends. Forced alignment can provide that starting point, but readable captions still require phrase grouping and a check against the final edit.

Download the caption timing worksheet · Create a narration to caption

API documentation checked September 14, 2026. The timing values below are invented teaching examples, not an API response or an accuracy benchmark. The example request is illustrative and was not sent to ElevenLabs.

Choose alignment when the words are already known

ElevenLabs Forced Alignment accepts audio and supplied text to produce time-aligned transcript information. It is useful when you already know the spoken words. If you do not have a transcript, speech recognition is the earlier step.

The distinction matters because an approved writing script may not match the recording. A narrator can omit a phrase, repeat a word, or change “select” to “choose.” Before alignment, make the transcript describe the actual finished performance.

For synthetic narration, create and approve the audio in Voice Lab, then export the final take. The alignment step in this article uses ElevenLabs externally. Generating a voiceover in QuestStudio does not automatically supply this API’s word timestamps.

Prepare a clean spoken transcript

Our original example is a short design tutorial: “Choose the blue brush. Paint inside the outline.” Save those words in a plain UTF-8 text file after confirming them against the audio. Remove performance tags, headings, scene directions, and speaker labels that were not spoken.

The capability documentation says to supply plain text and notes that diarization—assigning words to different speakers—is not supported by this operation. If your project has several speakers, keep that editorial information separately rather than inserting names into the text as if the names were spoken.

Listen particularly carefully to repeated words and corrections. “Paint, paint inside the outline” is different from a clean sentence. Either edit the audio and approve a new master or include the repetition in the transcript. Do not expect alignment to resolve an editorial disagreement between the files.

Make the request against the finished file

The API reference documents a multipart request to /v1/forced-alignment with an audio file and text. It returns word and character timing fields. The official quickstart also provides SDK examples.

This minimal Python example reads local files and saves the response without printing the API key. It requires the requests package and an ELEVENLABS_API_KEY environment variable. Running it uploads the selected audio and transcript to ElevenLabs and may incur the account’s current usage charges.

import os
from pathlib import Path
import requests

transcript = Path("spoken-transcript.txt").read_text(encoding="utf-8")
with Path("approved-narration.wav").open("rb") as audio:
    response = requests.post(
        "https://api.elevenlabs.io/v1/forced-alignment",
        headers={"xi-api-key": os.environ["ELEVENLABS_API_KEY"]},
        files={"file": ("approved-narration.wav", audio, "audio/wav")},
        data={"text": transcript},
        timeout=120,
    )
response.raise_for_status()
Path("alignment.json").write_text(response.text, encoding="utf-8")

Use a short, non-sensitive project sample for your first check. Confirm current upload limits in the interface or endpoint you use; the overview and API reference can differ, so do not build a large-file workflow around a remembered limit.

Turn word times into readable phrases

A list of word timestamps is not yet a good subtitle track. Decide which words belong together, where the phrase begins, and when it should leave the screen. For most instructional captions, meaningful phrases are easier to read than rapidly replacing one isolated word at a time.

Consider these invented word times for the first sentence. They demonstrate the arithmetic only:

A first caption draft could group the sentence from 0.40 to 1.55 seconds. Its speech span is 1.15 seconds. That tells you where the words occur; it does not prove the display time is comfortable. Review the surrounding pause and next cue before extending the caption for readability.

Keep “blue brush” together because it identifies the object. If the next sentence begins at 1.90 seconds, do not extend the first cue into it without considering the transition. Watch the actual brush selection while reviewing the text.

Translate clip time into timeline time

Alignment timestamps are relative to the submitted audio file. If that file begins three seconds into your video timeline, add three seconds to its word times. In the example, the first word moves from 0.40 seconds in the audio file to 3.40 seconds in the video.

Write the offset down rather than dragging the entire subtitle track by eye. If every cue is late by the same amount, a consistent offset is a likely place to investigate. If the beginning matches but later cues drift, inspect speed changes, cuts, or a different audio master.

Re-align after editing the spoken content or changing playback speed. Trimming a pause in the middle changes later timing even when the words remain identical. A caption file belongs to a particular audio version, not merely to a script title.

Find mismatches before styling

Inspect very short, zero-length, overlapping, or unexpectedly long word spans. These are review flags, not automatic proof that the service failed. A pause, repeated word, or transcript mismatch can make a local region difficult to align.

If “blue” lands during silence, listen around that section and compare the exact text. Did the speaker say “dark blue”? Did the audio contain an extra introductory phrase? Fix the mismatch at its source and run the alignment again on the corrected pair.

The API exposes a loss field, but do not invent a universal pass threshold from the name. For a short tutorial, direct listening and timeline inspection are more actionable than treating an undocumented number as a percentage of accuracy.

Export and review the captioned video

Create your subtitle file or caption track in the editor you use. Preserve phrase boundaries, avoid covering the demonstrated action, and keep important negations with their verbs. If you add translated captions, align the source timing first and review translation length separately.

Play the final export at normal speed with sound on. Then mute it and follow the instruction from the captions alone. The first pass checks agreement; the second checks whether the text stays visible long enough and names the action clearly.

Archive the exact audio master, spoken transcript, raw alignment response, timeline offset, and final caption file together. When someone asks for a shorter introduction, you can identify which timing needs to change instead of patching a subtitle track whose source is uncertain.

Frequently asked questions