2026-11-19 · 6 min read

How to Add Captions to Videos in Flutter

A film strip of mobile app scenes, the middle frame showing the captioned word FLUTTER
This image was generated with AI.

Flutter apps that record or share video get the captions request quickly, especially social and community apps where most watching happens with the sound low or off in feeds. You can render text over the player yourself, or burn captions into the file with an API. The right choice depends on whether the captioned video needs to leave the app.

Option 1: on-device text over the player

With video_player you can stack a Text widget over the video and drive it from a parsed subtitle file. The upside is full control and free rendering. The downside is that the captions live in your app only: when the user shares the video, the captions stay behind. If the share target is a feed where the video autoplays silently in preview, that is exactly where captions earn their keep.

Option 2: burn captions in with an API

For shareable output, send the video to caption.sh and get back a finished file with captions baked in. The request is one POST with a source_url and an options object for the caption look.

final res = await http.post(
  Uri.parse('https://api.caption.sh/v1/videos'),
  headers: {
    'Authorization': 'Bearer $apiKey',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'source_url': videoUrl,
    'options': {'position': 'bottom', 'max_words': 4},
  }),
);
final jobId = jsonDecode(res.body)['job_id'];

Then poll the job until it finishes. Statuses are queued, awaiting_upload, running, done, error; give the loop a timeout as well as the two terminal states.

var status = 'queued';
final deadline = DateTime.now().add(const Duration(minutes: 10));
while (status != 'done') {
  if (DateTime.now().isAfter(deadline)) {
    throw Exception('timed out');
  }
  await Future.delayed(const Duration(seconds: 5));
  final r = await http.get(
    Uri.parse('https://api.caption.sh/v1/jobs/$jobId'),
    headers: {'Authorization': 'Bearer $apiKey'},
  );
  status = jsonDecode(r.body)['status'];
  if (status == 'error') throw Exception('captioning failed');
}

The result endpoint redirects to the finished file, so do not follow redirects automatically; read the Location header and download from there. Results are stored for 24 hours, then deleted.

Practical notes

  • One job covers up to 10 minutes of video; segment longer recordings first.
  • Pricing is $0.10 per minute, prepaid, which makes per-share cost easy to model.
  • A 429 response means the transcription throughput ceiling: back off and retry.
  • Burned-in captions cannot be toggled or resized. If your player supports caption tracks, keep those enabled too for accessibility.

If the captioned video is the thing your users share, the API path turns captioning into a single async call instead of a rendering problem you maintain across devices.

Back to all articles