How to add subtitles to Mux videos

Mux takes SRT and WebVTT files. It turns each file into a text track on the asset. Mux serves the track as WebVTT in the HLS stream. If you are not sure which format to make, read subtitle formats explained.

You add a track with the Mux API. A track needs a URL: Mux downloads the file from that URL. It does not take a file upload.

Steps

1. Put the subtitle file where Mux can download it. Use your own storage or a file host, and copy the link. The Mux docs do not state an access rule for this link. The Mux Contentful guide says custom captions can come from any publicly available URL. If you use a signed link, make it last long enough for Mux to download the file.
2. Wait until the asset is ready. You can only add a track to a ready asset.
3. Send POST https://api.mux.com/video/v1/assets/{ASSET_ID}/tracks. Use your Mux access token ID and secret for Basic authentication.
4. Set type to text and text_type to subtitles. Both fields are required for a subtitle track.
5. Set language_code to a BCP 47 code, such as en or pt-BR. Set name to the label the viewer sees, or leave it out and Mux uses the language code. The name must be different for each text track.
6. If the file has captions for deaf and hard-of-hearing viewers, with sound cues such as [crowd cheers], set closed_captions to true.
7. Mux answers with status 201 and a track in the preparing state. The track works in the player when Mux finishes.

1{2  "url": "https://example.com/subtitles/launch-video.fr.vtt",3  "type": "text",4  "text_type": "subtitles",5  "language_code": "fr",6  "name": "Français",7  "closed_captions": false8}

Add tracks when you create the asset

You can also send tracks in the same request that creates the asset. Put the video first in the inputs array. Add one entry for each text track after it. Mux says there is no limit on the number of tracks in this request.

1{2  "inputs": [3    { "url": "https://example.com/video/launch-video.mp4" },4    {5      "url": "https://example.com/subtitles/launch-video.en.vtt",6      "type": "text",7      "text_type": "subtitles",8      "language_code": "en",9      "name": "English"10    },11    {12      "url": "https://example.com/subtitles/launch-video.fr.vtt",13      "type": "text",14      "text_type": "subtitles",15      "language_code": "fr",16      "name": "Français"17    }18  ],19  "playback_policies": ["public"]20}

Show a language by default

Add default_subtitles_lang to the HLS playback URL, with a BCP 47 code: https://stream.mux.com/{PLAYBACK_ID}.m3u8?default_subtitles_lang=en. If no track matches exactly, Mux picks the closest track in the same language: en picks en-US. Players show the default track even when a video autoplays with no sound. For a signed playback URL, put the parameter in the token.

On 2026.10.13, the Mux docs described no dashboard screen for adding a subtitle file to an asset. So this guide gives no dashboard menu path. Open an asset in your Mux dashboard and look for a text track option. If you do not find one, use the API steps above.

Two Mux integrations have their own caption screens. The Mux WordPress plugin takes custom caption files when you create the asset or later. Its Add Captions button in the Asset List makes auto-generated captions. In the Mux app for Contentful, use the Captions tab. The Contentful app takes a link to a VTT or SRT file.

Mux also runs its Robots caption workflows from the dashboard. They are in the Robots section below.

Mux makes captions from the audio of a video. It does this for on-demand video and for live streams. Mux names the speech model as OpenAI Whisper. There is no extra charge on on-demand video: the cost is part of the normal Mux Video encoding and storage fees.

Add a generated_subtitles array to the first entry of inputs. This works in a create asset request and in a direct upload (inside new_asset_settings). For an asset that exists, use POST /video/v1/assets/{ASSET_ID}/tracks/{AUDIO_TRACK_ID}/generate-subtitles.

1{2  "inputs": [3    {4      "url": "https://example.com/video/launch-video.mp4",5      "generated_subtitles": [6        { "language_code": "es", "name": "Español (auto)" }7      ]8    }9  ],10  "playback_policies": ["public"],11  "video_quality": "basic"12}

When the Mux captions are enough

Mux captions can be all you need. This is true when you need one language, the language is on the stable list, the audio is clear, and nobody has to approve the text before viewers see it. You pay nothing extra, and you write no subtitle file. Read the captions once before you publish: speech recognition makes errors with names, terms, and accents.

One Mux asset can have many text tracks. Each track has its own language code and name. Mux says there is no limit on the number of tracks in a create asset request, and we found no other limit. Mux players read the tracks from the HLS stream and show the languages the video has. The viewer picks a language there.

Translation with Mux Robots

The auto-generated captions are not translations: the language of the captions must match the spoken language. Mux has a separate Robots workflow, Translate captions. It takes an existing caption track and makes a track in another language. The Mux docs call Robots a beta product.

1. Get a source caption track on the asset. It can be a Mux auto-generated track or a file you added.
2. Send POST https://api.mux.com/robots/v0/jobs/translate-captions.
3. In parameters, set asset_id, track_id, and to_language_code. Send one job for each target language.
4. Wait for the robots.job.translate_captions.completed webhook. By default, Mux adds the new track to the asset.

On 2026.10.13, Mux listed starting rates of $0.001 per job and $0.005 per minute of video for this workflow. Every plan gets the first 100,000 Robots units each month free. One thousand units cost $0.01. Check the Mux pricing page before you plan a large library: Mux can change the rates.

Mux also lists Robots workflows named Generate premium captions and Edit captions. The first makes captions with optional speaker labels and word-level times. Mux marks the first one experimental. The second applies fixed text replacements and a profanity filter to a track.

Edit a track after upload

1. Download the track as a VTT file: https://stream.mux.com/{PLAYBACK_ID}/text/{TRACK_ID}.vtt. A signed asset needs a token.
2. Edit the file in a text editor or a subtitle editor.
3. Delete the old track with the Mux delete track API.
4. Add the edited file as a new track, as in the first section.

Check the file before you add it. The free SRT validator finds timing errors and overlaps, and the subtitle QC checklist lists the limits that viewers notice.

• Quality in many languages. The Mux speech recognition and the Mux Robots translation are machine output. Nobody checks the words before viewers see them, and the beta languages may be less accurate.
• Review. Mux has no place to assign a translator or a reviewer, to comment on a line, or to approve a track.
• Editing. Mux has no subtitle editor. To fix one line, you download, edit, delete, and add the track again.
• Timing. A tool that shows the audio waveform and checks reading speed is faster than a text editor for timing fixes.

If none of these apply, use the Mux options above.

CaptionsHero has no Mux integration. It makes and checks the subtitle files. You then add them to Mux with the API steps above.

1. Upload the video to CaptionsHero.
2. Make the subtitles. Use an AI draft, import an SRT or VTT file, or write them in the editor.
3. Add other languages. Use AI translation, or give each language to a translator.
4. Assign an editor and a reviewer for each language, then review with comments on exact lines (Team and Studio plans).
5. Approve each track (Team and Studio plans).
6. Download VTT or SRT for each language. Mux takes both. Use the approved version.
7. Put each file at a link Mux can download.
8. Add each file to the Mux asset with a create asset track request, as described in the first section. Set the language code and name for each file.

Studio plans have a REST API that downloads a track as SRT or VTT: GET /api/v1/tracks/{trackId}/captions.vtt. It returns the latest saved lines of the track, not the approved copy. You can use it in a script that sends the files to your storage and then to Mux.

Details

• All plans: AI transcription, AI translation in 82 languages, SRT and VTT import and export, and the editor with a waveform timeline and Netflix-style checks.
• Team and Studio: assignments, review comments, change requests, approval, and email notifications.
• Prices: Solo is free, Solo Pro is $29, Team is $149, and Studio is $399 for each month.

Other platform guides: Vimeo, Wistia, Bunny Stream, and Cloudflare Stream.