Subtitle Format Conversion with Bitmovin Encoding API

Overview

If your encoding workflow handles ingestion of separate subtitle input files, you can convert them to a different subtitle format by generating an output file with a different subtitle type. This conversion can be achieved programmatically via the Bitmovin Encoding API.

Step-by-Step Example: TTML → WebVTT

The following example demonstrates how to convert a TTML input file into WebVTT format and generate .vtt output files.

Step 1 — Define the FileInputStream

Read the subtitle input file by creating a FileInputStream object and setting its type to TTML.

FileInputStream fileInputStream = new FileInputStream();
fileInputStream.setFileType(FileInputStreamType.TTML); // Allowed: TTML, SRT, WEBVTT
fileInputStream.setInputId(s3Input.getId());
fileInputStream.setInputPath("sampleTTML.xml");
fileInputStream = bitmovinApi.encoding.encodings.inputStreams.file.create(encoding.getId(), fileInputStream);

Step 2 — Create a WebVTT Configuration

Define the target subtitle format by creating a WebVttConfiguration.

WebVttConfiguration webVttConfiguration = new WebVttConfiguration();
webVttConfiguration.setName("WebVTT_sample");
webVttConfiguration = bitmovinApi.encoding.configurations.subtitles.webvtt.create(webVttConfiguration);

Step 3 — Create a Stream

Link the input stream and the WebVTT configuration together using a Stream object.

Stream stream = new Stream();
stream.setCodecConfigId(webVttConfiguration.getId()); // Apply WebVTT configuration

StreamInput stream_streamInput = new StreamInput();
stream_streamInput.setInputStreamId(fileInputStream.getId()); // Reference the TTML input
stream_streamInput.setSelectionMode(StreamSelectionMode.AUTO);
stream.setInputStreams(List.of(stream_streamInput));

stream = bitmovinApi.encoding.encodings.streams.create(encoding.getId(), stream);

Step 4 — Mux to a `.vtt` File

Use a TextMuxing to write the converted subtitles to your desired output location.

TextMuxing textMuxing = new TextMuxing();
textMuxing.setFilename("subtitle.vtt");

EncodingOutput textMuxing_encodingOutput = new EncodingOutput();
AclEntry textMuxing_encodingOutput_aclEntry = new AclEntry();
textMuxing_encodingOutput_aclEntry.setPermission(AclPermission.PUBLIC_READ); // or PRIVATE
textMuxing_encodingOutput.setAcl(List.of(textMuxing_encodingOutput_aclEntry));
textMuxing_encodingOutput.setOutputId(s3Output.getId());
textMuxing_encodingOutput.setOutputPath("yourOutputPath/subtitles/webvtt/");
textMuxing.setOutputs(List.of(textMuxing_encodingOutput));

textMuxing.setStreamConditionsMode(StreamConditionsMode.DROP_MUXING);

MuxingStream textMuxing_muxingStream = new MuxingStream();
textMuxing_muxingStream.setStreamId(stream.getId());
textMuxing.setStreams(List.of(textMuxing_muxingStream));

textMuxing = bitmovinApi.encoding.encodings.muxings.text.create(encoding.getId(), textMuxing);

Supported Input Formats

The FileInputStream object currently supports the following subtitle input formats:

Format	`FileInputStreamType` value
TTML	`FileInputStreamType.TTML`
SRT	`FileInputStreamType.SRT`
WebVTT	`FileInputStreamType.WEBVTT`

⚠️ Limitations

Input formats: Only TTML, SRT, and WEBVTT are supported as input via FileInputStream.
Conversion combinations: Not all format-to-format conversions are supported. Refer to the supported combinations overview for details.

Need help? If your specific use case isn't working as expected, reach out to the Bitmovin Support team.