Add captions
Adding captions and subtitles to your video library.
Add or modify a caption
To create or modify a caption on a video a Cloudflare API Token is required.
The <LANGUAGE_TAG>
must adhere to the BCP 47 format. For convenience, the most common
language codes are provided at the bottom of this document.
If the language you are adding isn’t included in the table, you can find the value
through the The IANA registry, which maintains a list of language codes. To find the
value to send, search for the language. Below is an example value from IANA when
we look for the value to send for a Turkish subtitle:
%%Type: languageSubtag: trDescription: TurkishAdded: 2005-10-16Suppress-Script: Latn%%
The Subtag
code indicates a value of tr
. This is the value you should send
as the language
at the end of the PUT request shown above.
A label is generated from the provided language. The label will be visible for
user selection in the player. For example, if sent tr
, the label Türkçe
will
be created; if sent de
, the label Deutsch
will be created.
curl -X PUT \ -H 'Authorization: Bearer <API_TOKEN>' \ -F file=@/Users/mickie/Desktop/example_caption.vtt \https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>
Example Response to Add or Modify a Caption
{ "result": { "language": "en", "label": "English" }, "success": true, "errors": [], "messages": []
}
List the captions associated with a video
To view captions associated with a video:
curl -H 'Authorization: Bearer <API_TOKEN>' \https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions
Example response to get the captions associated with a video
{ "result": [ { "language": "en", "label": "English" }, { "language": "de", "label": "Deutsch" } ], "success": true, "errors": [], "messages": []
}
Directly access captions
To directly access the captions for your video, use the following URI and add in your video’s UID and language tag:
https://customer-{CODE}.cloudflarestream.com/<VIDEO_UID>/caption/<LANGUAGE_TAG>
Delete the captions
To remove a caption associated with your video:
curl -X DELETE \ -H 'Authorization: Bearer <API_TOKEN>' \ https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/stream/<VIDEO_UID>/captions/<LANGUAGE_TAG>
If there is an entry in errors
response field, the caption has not been
deleted.
Example response to delete the caption
{ "result": "", "success": true, "errors": [], "messages": []
}
Limitations
- A video must be uploaded before a caption can be attached to it. In the following
example URLs, the video’s ID is referenced as
media_id
. - Stream only supports WebVTT formatted caption files. If you have a differently formatted caption file, please use a tool to convert your file to WebVTT prior to uploading it.
- Videos may include several language captions, but each language must be unique. For example, a video may have English, French, and German captions associated with it, but it cannot have two French captions.
- Each caption file is limited to 10 MB in size. Please contact support if you need to upload a larger file.
Most common language codes
Language Code | Language |
---|---|
zh | Mandarin Chinese |
hi | Hindi |
es | Spanish |
en | English |
ar | Arabic |
pt | Portuguese |
bn | Bengali |
ru | Russian |
ja | Japanese |
de | German |
pa | Panjabi |
jv | Javanese |
ko | Korean |
vi | Vietnamese |
fr | French |
ur | Urdu |
it | Italian |
tr | Turkish |
fa | Persian |
pl | Polish |
uk | Ukrainian |
my | Burmese |
th | Thai |