Convert MP4 to SRT (subtitle track)

To convert MP4 to SRT (subtitle track), send one POST to /v1/subtitle-extract with the MP4 source and "to": "srt" in the body. "srt" is the schema default of "to", so the field may also be left out. Each call costs $0.003 in USDC on Base via x402, with no account and no API key. The source file can be up to 200 MB.

Endpoint

POST /v1/subtitle-extract

Price

$0.003 per call

Service

subtitle-extract

Docs

/docs/subtitle-extract

01Limits

02Example

A real MP4 to SRT run of subtitle-extract.

POST /v1/subtitle-extract
content-type: application/json
payment-signature: <base64 x402 payload>

{
  "url": "https://grist.tools/samples/av/pair-clip.mp4",
  "stream": 0,
  "to": "srt"
}

200 OK
payment-response: <base64 settlement receipt>

{
  "source_url": "https://grist.tools/samples/av/pair-clip.mp4",
  "bytes": 11315,
  "container": "mp4",
  "stream_index": 0,
  "format": "srt",
  "cue_count": 2,
  "subtitle": "1\n00:00:00,000 --> 00:00:01,750\nRain taps on the window.\n\n2\n00:00:02,250 --> 00:00:03,750\nA lamp glows in the hall.\n\n"
}

Source file: av/pair-clip.mp4, 11 KB (11,315 bytes). 4 s MP4 made by ffmpeg: a 64x36 PNG video stream at 1 fps (a slate field with a small amber square moving right), a mono 8 kHz FLAC audio track of two 500 Hz triangle beeps, and an English mov_text subtitle stream with two cues. The request sets stream to 0. The recorded run returned 117 bytes of SRT, 1% of the source size, with the source read as the mp4 container, stream index 0 and 2 cues. Recorded with ffmpeg 8.1.2.

In the sample itself, the ftyp box names major brand isom, minor version 512 and compatible brands isom, iso2 and mp41; the top-level boxes run ftyp, free, mdat and moov, so the moov index comes after the media data; mvhd counts 4,000 ticks at 1,000 per second, 4 s; the 3 tracks are vide with sample entry mp4v, soun with sample entry fLaC and sbtl with sample entry tx3g. The returned text starts with cue number 1. Its 2 timing lines are 00:00:00,000 --> 00:00:01,750 and 00:00:02,250 --> 00:00:03,750, giving hours, minutes and seconds, and a comma before the milliseconds. Every cue has a number line above its timing, 1 and 2.

03Format notes

MP4 as a source

MP4 belongs to the ISO base-media family, and Grist recognises it by the ftyp box type at bytes four to eight rather than by a file extension. QuickTime MOV and other files carrying the same box are sniffed as this one container, and the response names it mp4. The container can hold video, audio and text subtitle streams side by side, and each service takes one kind. audio-convert maps the first audio stream and drops the picture. video-thumbnail puts the seek before the input, so it happens at the demuxer and stays cheap in a large file, then decodes exactly one frame from the first video stream. subtitle-extract selects a text track by its zero-based position among subtitle streams. Each ffmpeg run strips container metadata and sets bit-exact flags, so outputs do not carry creation timestamps.

SRT as a target

SRT written by subtitle-convert numbers its cues sequentially from one and prints every timestamp as HH:MM:SS,mmm with a comma before the milliseconds, hours always included. When the source is WebVTT, each cue is rebuilt from its start, end and text, so cue identifiers, positioning settings and NOTE blocks do not survive. SubRip is also the default destination of subtitle-extract, which pulls a text subtitle stream out of a media container and writes it with ffmpeg's srt muxer instead of the JavaScript serialiser. That route refuses a stream that produces no text rather than returning an empty file, and it reports a cue count obtained by counting the timing arrows in the output. The two routes share the destination format but not the code that writes it. In the subtitle-convert file, each block stacks its index line, its timing line and its caption text, consecutive blocks are parted by one empty line, and one line feed closes the file.

Note: The container must carry a text subtitle track; image-based subtitles cannot be turned into text.

04Errors

When each is raised, and what it means for payment: /docs/subtitle-extract.

05Questions

What does it cost to convert MP4 to SRT?

$0.003 per call, paid in USDC on Base via x402.

How large can the MP4 file be?

Up to 200 MB (209,715,200 bytes). Past a limit the call answers too_large (413).

What happens if the conversion fails?

The tool answers with a typed JSON error from the errors table. Payment is settled only after the tool has produced its result; a call that fails inside the tool is never settled.

06Related

• Audio & video guide
• AVI to SRT
• MKV to SRT
• Ogg to SRT
• WebVTT to SRT