How to Burn SRT Subtitles Into Video With Codex and FFmpeg

To burn SRT subtitles into an MP4, give an FFmpeg workflow one authorized HTTPS URL for the source video and one for the subtitle file, render a new H.264 and AAC MP4, and then inspect the returned asset. The subtitles become part of every video frame, so they remain visible in players and social platforms that ignore separate caption tracks.

This guide uses Codex with Aident Loadout's hosted FFmpeg Actions. The agent discovers the current contract, preflights the exact inputs, runs FFmpeg outside your local machine, and returns a downloadable video asset. You still review timing, readability, and output streams before publishing.

Choose Burned Subtitles for the Right Job

Burned subtitles are permanent pixels. Viewers cannot turn them off, change their font, or select the text. Use them when:

• a social platform may drop or ignore a separate caption track;

• every viewer must see the same translation or annotation;

• the delivery system accepts one finished video file; or

• you need a predictable preview that matches the final frame.

Use a selectable subtitle stream or sidecar SRT instead when accessibility, search, localization, or viewer control matters. Keep the original SRT even after you burn it into the video. The source file remains useful for corrections, translations, transcripts, and accessible players.

FFmpeg's official subtitles filter documentation describes the underlying libass-based render path. Burning captions filters and re-encodes the video. It is different from stream copying, which does not decode and filter the frames.

Prepare a Clean Video and SRT Pair

Start with one final source video and one UTF-8 SRT file. Check the subtitle structure before paying for a render:

1
00:00:01,200 --> 00:00:03,800
This caption appears for 2.6 seconds.

2
00:00:04,100 --> 00:00:06,600
The next caption starts after a short gap

Each cue needs a numeric index, a start and end time using commas for milliseconds, one or more text lines, and a blank line before the next cue. Confirm that:

1. the first caption begins at the intended moment;

2. no cue ends before it starts;

3. overlapping cues are intentional;

4. the file is saved as UTF-8;

5. line lengths fit the target frame; and

6. names, numbers, and punctuation match the approved transcript.

Do not send a draft transcript into a final render. A one-character timing or spelling fix requires another full video encode.

Set Up Aident Loadout

Give Codex the canonical setup instruction exactly as written:

Follow https://aident.ai/SETUP.md

Then verify the installed public CLI and connected accounts:

aident account auth status
aident vault vault --action status

Ask Codex to discover Actions by job, not from a copied identifier:

aident capabilities search \
  --targetEnv staging \
  --queries '["inspect one video file","burn one SRT subtitle file into an MP4"]' \
  --types '["action"]'

Use staging for discovery when your CLI supports it. Copy the exact current Action names from the result, then inspect their descriptions, input schemas, output schemas, examples, pricing, and risk before execution. In this guide, the public agent-facing jobs are Inspect Media and Burn Subtitles MP4. Catalog names and versions can change, so the live result is the source of truth.

On August 11, 2026, Burn Subtitles MP4 required two HTTPS URLs named inputUrl and subtitlesUrl. It returned an H.264 and AAC MP4 asset, carried risk level 0, and preflighted at a dynamic range of one to eight Aident credits. Inspect Media required one HTTPS inputUrl, was read-only, and had the same quoted range. Treat those as dated observations, not a permanent schema or price.

Step 1: Put Both Inputs Behind Authorized HTTPS URLs

Hosted Actions cannot read a path on your laptop such as /Users/me/video.mp4. Upload the video and SRT through an authorized file-storage Action, then pass the returned short-lived HTTPS URLs to FFmpeg.

Keep a small manifest so the two inputs cannot drift between review and execution:

{
  "jobId": "captions-2026-08-11-01",
  "inputUrl": "<authorized-source-video-url>",
  "subtitlesUrl": "<authorized-srt-url>",
  "language": "en",
  "transcriptRevision": "approved-3",
  "expectedDurationSeconds": 94.2
}

Use the shortest practical URL lifetime, but leave enough time for the remote worker to download both files. Do not paste cloud credentials, browser cookies, provider keys, or a private local path into the prompt.

Step 2: Inspect the Source Video

Run Inspect Media on the authorized video URL before rendering. Record:

• container and video codec;

• width, height, and display aspect ratio;

• frame rate;

• duration;

• audio codec and channel layout; and

• any rotation or unusual stream metadata.

Stop if the duration differs from the approved transcript timeline, the video has no decodable video stream, the URL is expired, or the dimensions are not the intended delivery size. A subtitle file timed against a 60-second edit will not become correct when applied to a 63-second export.

Step 3: Preflight the Exact Burn

Preflight the reviewed pair before dispatching FFmpeg:

aident capabilities preflight \
  --name "<exact Burn Subtitles MP4 Action from discovery>" \
  --input '{"inputUrl":"<authorized-source-video-url>","subtitlesUrl":"<authorized-srt-url>"}'

Confirm that the input is valid and that the quote is within your ceiling. Do not swap either URL after review. If preflight reports an invalid URL, unsupported field, missing connection, or unavailable estimate, fix that boundary instead of calling another provider directly.

The burn Action performs a write because it creates a new asset, even though its current risk level is 0. The source video remains unchanged.

Step 4: Render One Output

Execute the exact payload that passed preflight once. Ask Codex to return:

• the Action receipt;

• exit code and duration;

• output asset ID and download URL;

• standard error for FFmpeg diagnostics; and

• the final Aident credit cost.

An exit code of zero means FFmpeg completed the command. It does not prove that captions are readable, timed correctly, or present in the frames. Save the output under a new revision rather than replacing the source video.

If the run fails, use the returned diagnostic first. Common causes include an expired input URL, malformed SRT timing, non-UTF-8 text, an unsupported source stream, or subtitle characters unavailable to the renderer. Do not retry unchanged input repeatedly.

Step 5: Inspect and Review the Returned MP4

Run Inspect Media again on the output URL. Confirm:

Then watch the full video, not just the first cue. Review the first and last caption, the fastest sequence, every line break, names and numbers, and captions near a cut. Check the smallest target device as well as a desktop player.

For a durable acceptance record, keep the input manifest, transcript revision, Action receipt, output asset ID, quote, final cost, and reviewer decision together.

Common Failure Modes

The MP4 has a subtitle stream, but captions are not visible

That usually describes muxed, selectable subtitles rather than burned captions. The accepted output must show the text in the video frames even when the player has captions disabled.

Captions are early or late by a constant amount

Correct the SRT timestamps or the approved video edit. Do not hide an offset problem by trimming the final file without updating the source manifest.

Accented or non-Latin characters render incorrectly

Confirm UTF-8 encoding and test representative characters before the full render. Font availability and shaping belong to the renderer's current contract. Do not assume a font installed on your laptop exists in the hosted environment.

The result looks softer or larger than the source

Burning subtitles requires video filtering and re-encoding. Review visual quality and file size against the delivery target instead of expecting byte-for-byte preservation.

Codex reports success without a usable asset

Require an asset ID, a working download URL, a zero exit code, and a media inspection result. A command transcript alone is not the deliverable.

Reusable Codex Prompt

Follow https://aident.ai/SETUP.md

Burn the reviewed SRT subtitles into one authorized MP4.

1. Confirm Aident authentication and Vault status.
2. Discover the current Actions for inspecting a video and burning an SRT file
   into an MP4. Use staging for discovery when supported.
3. Inspect both live schemas, pricing, and risk. Do not reuse an old Action ID.
4. Process only the inputUrl and subtitlesUrl in my approved manifest.
5. Inspect the source video and stop if its duration or streams differ from the
   manifest.
6. Preflight the exact burn payload. Show me the validation and credit range.
7. Execute once only if preflight is valid and within my stated ceiling.
8. Inspect the returned MP4 and give me the receipt, diagnostics, asset ID,
   download URL, duration, streams, quote, and final cost.
9. Do not publish, overwrite the source, expose credentials, or retry unchanged
   failed input

Success means the reviewed MP4 is downloadable, has the expected H.264 and AAC streams and duration, displays every caption at the approved time, and has a complete receipt. Measure first-pass acceptance, timing corrections per minute, rerender rate, output size, render duration, and credits per accepted video.

For a broader editing workflow, read How to Edit Videos With Claude Code and HyperFrames. If your source needs localization first, pair it with How to Translate a Video With Codex and HeyGen. For the connection and approval model, use How to Connect Claude Code and Codex to Real-World Tools.

Set up Aident Loadout and burn subtitles into one reviewed video.

Sources

• FFmpeg subtitles filter, official FFmpeg filter documentation, accessed August 11, 2026

• FFmpeg stream copy, official FFmpeg documentation, accessed August 11, 2026