Bring your own transcript

By default, the Dubbing API transcribes your source media and machine-translates the transcript into each target language. If you already have an accurate transcript — subtitles, a script, or professionally translated text — you can supply it instead. This guide covers the transcript file format, how to create a project from a transcript, and how to provide your own translations when adding a language.

Transcript file format

A transcript is a JSON file with a single top-level segments array. Each segment is one utterance: the text spoken, when it starts and ends, and optionally who speaks it.

1
{
2
  "segments": [
3
    {
4
      "external_id": "line_0",
5
      "speaker_id": "speaker_0",
6
      "start_s": 0.0,
7
      "end_s": 14.5,
8
      "text": "With my soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditation guides, or adding an intimate feel to your narrative projects."
9
    }
10
  ]
11
}

Segment rules

The transcript is validated when you create the project:

• Segments must be ordered by start_s.
• A segment must be between 0.1 and 25 seconds long, and end_s must be greater than start_s.
• Segments with the same speaker_id must not overlap, although they may touch at an endpoint. Segments from different speakers may overlap to represent simultaneous speech.
• A transcript may contain at most 20,000 segments and the file may be at most 4 MiB.

Prefer shorter segments over longer ones: break sentences wherever there is a pause of one second or longer. Segment boundaries determine how the dubbed audio is timed against the source, so a transcript with accurate, natural breaks produces a better-synchronized dub.

Create a project from your transcript

Pass the transcript file when creating the project. source_language is required when providing a transcript, since the source media is not transcribed automatically.

1
import os
2
from dotenv import load_dotenv
3
from elevenlabs.client import ElevenLabs
4
5
load_dotenv()
6
7
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
8
9
with open("transcript.json", "rb") as transcript:
10
    project = elevenlabs.dubbing.project.create(
11
        source_url="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3",
12
        source_language="en",
13
        transcript=transcript,
14
    )
15
16
print(project.project_id)

The project still ingests the source media before it can be dubbed, so poll it until its status is ready, as shown in the quickstart. Your segments are used as-is; no automatic transcription runs.

Provide your own translations

When adding a language target, pass a translations map to use your own translations instead of machine translation. The map is keyed by each source segment’s external_id, or by its internal segment id if you did not supply one, and must cover every source segment exactly once.

1
project_id = "proj_1601kwkyxp0hfzvtmyxwqxx6mcy3"
2
3
language = elevenlabs.dubbing.project.language.create(
4
    project_id,
5
    target_language="fr",
6
    translations={
7
        "line_0": "Avec mon accent américain doux et murmuré, je suis le choix idéal pour créer du contenu ASMR, des guides de méditation, ou pour apporter une touche d'intimité à vos projets narratifs.",
8
    },
9
)

Each language target takes one create call, so repeat this request for every language you want to dub into. A translations map may contain at most 20,000 entries totalling at most 4 MiB of text.

If your segments have no external_id, read the source transcript to obtain each segment’s internal id and use those as keys instead:

1
transcript = elevenlabs.dubbing.project.transcript.get(project_id)
2
for segment in transcript.segments:
3
    print(segment.id, segment.text)

Seed translations at project creation

For a single target language, you can skip the separate translations map by including a translation on every segment in the transcript file and passing target_language when creating the project. The language target is created queued with your translations and begins generating once the project is ready.

1
{
2
  "segments": [
3
    {
4
      "external_id": "line_0",
5
      "speaker_id": "speaker_0",
6
      "start_s": 0.0,
7
      "end_s": 14.5,
8
      "text": "With my soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditation guides, or adding an intimate feel to your narrative projects.",
9
      "translation": "Avec mon accent américain doux et murmuré, je suis le choix idéal pour créer du contenu ASMR, des guides de méditation, ou pour apporter une touche d'intimité à vos projets narratifs."
10
    }
11
  ]
12
}

Quality considerations

The dub is only as good as the transcript and translations it is built from. Segment timings and text are used directly to time and voice the dubbed performance, so inaccurate timings or text degrade the output. Translations are rendered to fit their segment’s time span: a translation that is much longer or shorter than the original affects the pacing of the dubbed speech, so aim for translations of comparable spoken length.

Next steps