Docs/AgentEyes/Multilingual subtitles
AgentEyes

Multilingual subtitles

4 min read

Once a recording has a transcript, AgentEyes can put it into another language and write those captions onto the video. It is two steps: translate the transcript into the language you want, then subtitle - burn those captions into a new video file. You can stop after translate if all you need is the caption file.

Transcripts are WebVTT, one file per language

Every transcript is stored as standard WebVTT (a .vtt subtitle file), named per language: transcript.en.vtt for English, transcript.tr.vtt for Turkish, and so on. Translating adds another .vtt beside the original; the recording can carry several languages at once. WebVTT is the format browsers and tools like Teams understand, so the caption files are useful on their own.

Translate a transcript

Translate takes the recording id (from the library, or printed by import) and a target language code:

Translate a recording into Turkish
agenteyes translate <id> --to tr

The timing is preserved exactly - each caption keeps its original start and end, so the translated captions line up with the video cue for cue. Use a short language code such as tr, es, fr, de, ja, or a regional code like pt-BR. It writes transcript.<lang>.vtt and reports the language and how many cues it wrote:

[ok] translating 84 cue(s) en -> tr ...
[ok] wrote 84 cue(s) -> transcript.tr.vtt
Note
Translation uses DevThrottle's hosted AI, so the transcript text is sent to DevThrottle through your signed-in account to be translated. You need to be signed in to DevThrottle to translate. (Burning the captions in the next step is fully local - see below.)
Tip
Translate reads whatever transcript the recording already has - English if present, otherwise another language it already carries. If a recording has no transcript at all yet, transcribe it first by importing it or building a walkthrough from it.

Burn the captions into a video

Subtitle renders a brand-new video with the captions burned in. It needs the recording to have a video and to already carry the .vtt for that language (so translate first, unless the language is already there):

Burn Turkish captions into a new video
agenteyes subtitle <id> --lang tr

It writes recording.<lang>.subtitled.mp4 (for example recording.tr.subtitled.mp4) in the recording folder. Your original video is never touched - the subtitled version is a separate file. Burning runs locally with the bundled ffmpeg; nothing is sent anywhere for this step.

[ok] burning tr captions into recording.tr.subtitled.mp4
[ok] wrote recording.tr.subtitled.mp4
Note
If the language has no .vtt yet, subtitle stops with a clear message telling you to translate that language first, rather than producing an empty file.

Over the Control API

Both steps run over the local Control API.

POST/transcripts/{id}/translate
Translate the recording's transcript. Body: { "to": "tr" }. Returns the language, the cue count, and the VTT file name.
POST http://127.0.0.1:7882/transcripts/<id>/translate
// response
{
  "id": "<recording-id>",
  "dir": "...\\AgentEyes\\<recording-id>",
  "language": "tr",
  "cues": 84,
  "vtt": "transcript.tr.vtt"
}
POST/recordings/{id}/subtitle
Burn a language's captions into a new video. Body: { "language": "tr" }. Returns the output file name.
POST http://127.0.0.1:7882/recordings/<id>/subtitle
// response
{
  "id": "<recording-id>",
  "dir": "...\\AgentEyes\\<recording-id>",
  "language": "tr",
  "output": "recording.tr.subtitled.mp4"
}

Where to go next

To bring an outside video in first so you have something to caption, see Import a video. For every command and its options, see the CLI reference.