2026-11-17 · 6 min read

How to Add Captions to Videos in Swift

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

If your iOS app records, edits, or shares video, captions come up fast. Social platforms trained users to expect text on screen, and Apple surfaces caption quality in accessibility audits. This guide covers the two realistic paths in Swift: rendering text yourself with AVFoundation, or sending the video to an API that returns a finished, captioned file.

Option 1: AVFoundation text layers

AVFoundation can overlay text with CATextLayer inside an AVMutableVideoComposition. You build a layer for each caption line, set its beginTime and duration, and attach the animation tool to the composition. It works offline and costs nothing, but you own everything: line breaking, timing drift, font scaling across device sizes, and export performance on older devices.

The hard part is not drawing text. It is getting a transcript with word-level timestamps in the first place. Speech.framework gives you transcription on device, but its segment timing is coarse, and splitting segments into readable two-line caption chunks is your problem.

Option 2: Burned-in captions with the caption.sh API

caption.sh takes a source video URL, transcribes it, and returns the same video with styled captions burned in. From an iOS app the flow is: upload the video somewhere addressable (S3, Cloudflare R2, or your own CDN), POST a job, poll until it finishes, then download the result.

// POST a caption job from Swift
struct CaptionJob: Encodable {
    let source_url: String
    let options: CaptionOptions
}
struct CaptionOptions: Encodable {
    let font: String
    let font_size: Int
    let font_color: String
    let position: String
}

let job = CaptionJob(
    source_url: "https://cdn.example.com/clips/take-12.mp4",
    options: CaptionOptions(font: "Inter", font_size: 48,
                            font_color: "#FFFFFF", position: "bottom")
)
var req = URLRequest(url: URL(string: "https://api.caption.sh/v1/videos")!)
req.httpMethod = "POST"
req.setValue("Bearer YOUR_API_KEY", forHTTPHeaderField: "Authorization")
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
req.httpBody = try JSONEncoder().encode(job)

Jobs move through queued, awaiting_upload, running, and done. Poll the status endpoint until you see done, then fetch /result, which replies with a 302 redirect. Read the Location header for the finished file URL. Rendered files stay available for 24 hours, so download or copy them to your own storage right away.

Which one should you pick

  • Use AVFoundation when captions must render offline, the transcript already exists, and you have the appetite to maintain layout code across screen sizes.
  • Use the API when you need accurate transcription, consistent styling, and batch processing without shipping a renderer.
  • Hybrid is common: caption preview clips through the API, and only invest in client-side rendering if a profiler proves you need it.

Cost and limits

Processing is $0.10 per minute of video, prepaid. Videos up to 10 minutes are accepted. A 429 response means you hit the throughput ceiling; back off and retry rather than hammering the endpoint.

For most apps the API path ships in an afternoon. The AVFoundation path ships in a few weeks and never really finishes. Pick accordingly.

Back to all articles