This document records guidelines and conventions on how subtitles should be handled in Opencast.

These guidelines are new to Opencast 15. Not all parts of Opencast may yet adhere to them!

Subtitles are expected to be in WebVTT format. Subtitles in other formats are expected to be converted to WebVTT prior to uploading them to Opencast.


In general, subtitles are stored as tracks in an event, much like audio and video streams. Subtitles stored this way are assumed to be related to audio and video tracks in the event.


For the flavor of a subtitle track, captions is recommended for the main flavor, while the sub-flavor should express the processing state (e.g. source, work, delivery). In the case of multiple subtitle tracks, they should all be stored in the same flavor, while being optionally differentiated by tags.


Tags are used to hold additional information about individual subtitle tracks. All tags are optional and components should work without them being present, falling back to generic displays, or not showing information at all.

The following is a list of tags that Opencast components may recognize: - lang:<language> - <language> represents a language code of the form en or en-US. - Based on the IETF BCP 47 language tag specification. - Can either be a two letter language code, or a two letter language code followed by a hyphen and a two letter region tag. Other subtags may not be supported by all Opencast services. - Specifies the languages most prominently used in the subtitle. - Even though all tags are optional, it is recommended to set this tag if possible, as it can help the most with user experience (For example, the Paella Player uses lang in its subtitle selection).

Mime Type

Since the format of subtitle tracks should always be WebVTT, the mime type should always be text/vtt.

Uploading and downloading subtitles

Subtitles can be up- and downloaded wherever other tracks can be up- and downloaded as well.

Admin UI

If you wish to configure subtitle upload in the Admin UI, check out Asset Upload Options.

Automatically generating subtitles in Opencast

Opencast allows for automatically generating subtites by adding certain operations to your workflows. Subtitles can be generated locally by open-source services, or externally by paid services.

For local generation, take a look at the Speech-To-Text Workflow Operation. As of writing, it supports vosk, whisper and whispercpp.

For external generation, various plugins are available: