Top

Articles in this section

DVB subtitle insertion

Last updated

Overview

The Video SDK supports inserting subtitle tracks into output streams such as DVB, UDP, SRT, and MPEG transport streams. 

Pay attention; this feature is going to be included in the Closed Caption plugin license.

The SDK supports two subtitle output types:

  • DVB subtitles - bitmap-based subtitles encoded with subtitle::codec='dvbsub'.
  • DVB Teletext subtitles - text-based subtitles encoded with subtitle::codec='dvbtxt'.

Both output types can be generated from text subtitle input files. The reader can use subtitle files directly through the external_subtitle property.

The supported input subtitle formats are:

  • .ass - Advanced SubStation Alpha subtitles
  • .srt - SubRip subtitles

ASS subtitles are recommended, because ASS files support text formatting through the ASS style header. The sample includes an example.ass file and loads it by default.

Multiple subtitle tracks can be attached to the reader at the same time. Each subtitle track can be assigned its own stream ID, output codec, and language metadata.

The same output can contain both subtitle output types at the same time. For example, one subtitle track can be encoded as DVB Teletext with subtitle::codec='dvbtxt', while another subtitle track can be encoded as bitmap DVB subtitles with subtitle.1::codec='dvbsub'.

You can find the ready-to-use samples here:

MPlatform

"C:\Program Files (x86)\Medialooks\MPlatform SDK\Samples Basic\C#\Subtitle Insertion Sample x64"

MFormats

"C:\Program Files (x86)\Medialooks\MFormats SDK\Subtitle Insertion Sample x64"

How to generate and insert subtitle tracks

The subtitle insertion process consists of the following steps:

  1. Prepare or generate subtitle tracks in .ass or .srt format.
  2. Attach one or more subtitle files directly to the reader with external_subtitle.
  3. Assign a stream ID to each subtitle track.
  4. Configure the writer subtitle codec, stream ID, language metadata, and optional subtitle formatting.
  5. Start the writer and play or process the source.

 

1. Prepare ASS or SRT subtitle files

The sample can load existing .ass or .srt subtitle files. It can also generate temporary subtitle files from the subtitle editor UI.

ASS is the default subtitle format because it allows the sample to store text formatting in the subtitle file header.

ASS generation example

string subFile = Path.Combine(Path.GetTempPath(), "temp_subtitle_track_0.ass");

File.WriteAllText(
    subFile,
    AssSubtitleHelper.BuildAss(
        track.Subtitles,
        styleSettings,
        "DVB Subtitle Inserter"
    )
);

SRT generation example

string subFile = Path.Combine(Path.GetTempPath(), "temp_subtitle_track_0.srt");

using var writer = new StreamWriter(subFile);

foreach (var subtitle in track.Subtitles)
{
    writer.WriteLine(subtitle.Index);
    writer.WriteLine($"{subtitle.StartTime} -- {subtitle.EndTime}");
    writer.WriteLine(subtitle.Text);
    writer.WriteLine();
}

The generated subtitle file is then passed directly to the reader. No VobSub conversion is required.
 

2. Attach subtitle files to the reader

Subtitle files are attached by setting external_subtitle reader properties. For a single subtitle track, use external_subtitle.

var subtitleFile = @"C:\Subtitles\example.ass";

var readerConfig =
    "subtitle_track=0 experimental.out_subtitle_packets=2 external_process=false " +
    $"external_subtitle='{subtitleFile}'";

For multiple subtitle tracks, use indexed external_subtitle properties. Each subtitle track can also be assigned a stream ID with external_subtitle.stream_id.

string subPath1 = @"C:\Subtitles\english.ass";
string subPath2 = @"C:\Subtitles\greek.ass";

string readerConfig =
    "external_process=false subtitle_track=0 experimental.out_subtitle_packets=2 " +
    "external_subtitle.stream_id=117 " +
    $"external_subtitle='{subPath1}' " +
    "external_subtitle.stream_id.1=118 " +
    $"external_subtitle.1='{subPath2}'";

The stream ID connects a specific reader subtitle track to the corresponding writer subtitle configuration. For example, the subtitle track assigned to external_subtitle.stream_id=117 can later be configured in the writer with subtitle::stream_id=117.

 

3. Configure writer subtitle tracks

The writer configuration defines how each subtitle track should be encoded in the output stream.

Use dvbsub when the output track should be encoded as bitmap DVB subtitles:

subtitle::codec='dvbsub'

Use dvbtxt when the output track should be encoded as DVB Teletext subtitles:

subtitle::codec='dvbtxt'

Each subtitle track can also have its own stream ID and language metadata.

Single bitmap DVB subtitle track

format='mpegts'
video::codec='libopenh264'
audio::codec='aac'
video::b='5M'
mux_buffers=0
subtitle::codec='dvbsub'
subtitle::stream_id=117
subtitle::metadata::language='eng'
video::maxrate='5M'
program::title='Medialooks DVB subtitles test'

Single DVB Teletext subtitle track

format='mpegts'
video::codec='libopenh264'
audio::codec='aac'
video::b='5M'
mux_buffers=0
subtitle::codec='dvbtxt'
subtitle::stream_id=117
subtitle::metadata::language='eng'
video::maxrate='5M'
program::title='Medialooks DVB Teletext test'

Multiple subtitle tracks can be configured by using indexed subtitle properties. In the example below, the first subtitle track is written as DVB Teletext and the second subtitle track is written as bitmap DVB subtitles.

format='mpegts'
video::codec='libopenh264'
audio::codec='aac'
video::b='5M'
mux_buffers=0

subtitle::codec='dvbtxt'
subtitle::stream_id=117
subtitle::metadata::language='eng'

subtitle.1::codec='dvbsub'
subtitle.1::stream_id=118
subtitle.1::metadata::language='greek'

video::maxrate='5M'
program::title='Medialooks subtitle test'

 

4. Configure subtitle formatting in the writer

Basic subtitle text formatting can also be configured directly in the writer configuration. These properties are useful for common styling options such as font, font size, colors, background, and outline.

The supported subtitle formatting properties are:

  • subtitle::font
  • subtitle::font_size
  • subtitle::font_color
  • subtitle::background - true or false
  • subtitle::background_color
  • subtitle::background_alpha
  • subtitle::outline - true or false
  • subtitle::outline_color
  • subtitle::outline_thickness
  • subtitle::outline_alpha - for bitmap DVB subtitles
format='mpegts'
video::codec='libopenh264'
audio::codec='aac'
video::b='5M'
mux_buffers=0

subtitle::codec='dvbsub'
subtitle::stream_id=117
subtitle::metadata::language='eng'

subtitle::font='Arial'
subtitle::font_size=26
subtitle::font_color='FFFFFF'
subtitle::background=true
subtitle::background_color='000000'
subtitle::background_alpha=128
subtitle::outline=true
subtitle::outline_color='000000'
subtitle::outline_thickness=2
subtitle::outline_alpha=255

video::maxrate='5M'
program::title='Medialooks subtitle test'

For indexed subtitle tracks, use the same indexed prefix as for other subtitle properties. For example, formatting for the second subtitle track can be set with subtitle.1::font, subtitle.1::font_size, and subtitle.1::font_color.

subtitle.1::codec='dvbsub'
subtitle.1::stream_id=118
subtitle.1::metadata::language='greek'
subtitle.1::font='Arial'
subtitle.1::font_size=26
subtitle.1::font_color='FFFFFF'
subtitle.1::outline=true
subtitle.1::outline_color='000000'
subtitle.1::outline_thickness=2

ASS headers are still supported and are useful when custom formatting is required in the subtitle file itself. For standard formatting, the writer subtitle formatting properties can be used directly in the encoder configuration.

MPlatform full example

string sourceFile = @"C:\Media\input.ts";
string subPath1 = @"C:\Subtitles\english.ass";
string subPath2 = @"C:\Subtitles\greek.ass";

string readerConfig =
    "external_process=false subtitle_track=0 experimental.out_subtitle_packets=2 " +
    "external_subtitle.stream_id=117 " +
    $"external_subtitle='{subPath1}' " +
    "external_subtitle.stream_id.1=118 " +
    $"external_subtitle.1='{subPath2}'";

MFileClass file = new MFileClass();
file.FileNameSet(sourceFile, readerConfig);

string writerConfig =
    "format='mpegts' video::codec='libopenh264' audio::codec='aac' " +
    "video::b='5M' mux_buffers=0 " +
    "subtitle::codec='dvbtxt' subtitle::stream_id=117 subtitle::metadata::language='eng' " +
    "subtitle::font='Arial' subtitle::font_size=26 subtitle::font_color='FFFFFF' " +
    "subtitle.1::codec='dvbsub' subtitle.1::stream_id=118 subtitle.1::metadata::language='greek' " +
    "subtitle.1::font='Arial' subtitle.1::font_size=26 subtitle.1::font_color='FFFFFF' " +
    "subtitle.1::outline=true subtitle.1::outline_color='000000' subtitle.1::outline_thickness=2 " +
    "video::maxrate='5M' program::title='Medialooks subtitle test'";

MWriterClass writer = new MWriterClass();
writer.WriterNameSet(outputUrl, writerConfig);

writer.ObjectStart(file);
file.FilePlayStart();

MFormats full example

string sourceFile = @"C:\Media\input.ts";
string subPath1 = @"C:\Subtitles\english.ass";
string subPath2 = @"C:\Subtitles\greek.ass";

string readerConfig =
    "external_process=false subtitle_track=0 experimental.out_subtitle_packets=2 " +
    "external_subtitle.stream_id=117 " +
    $"external_subtitle='{subPath1}' " +
    "external_subtitle.stream_id.1=118 " +
    $"external_subtitle.1='{subPath2}'";

MFReaderClass reader = new MFReaderClass();
reader.ReaderOpen(sourceFile, readerConfig);

string writerConfig =
    "format='mpegts' video::codec='libopenh264' audio::codec='aac' " +
    "video::b='5M' mux_buffers=0 " +
    "subtitle::codec='dvbtxt' subtitle::stream_id=117 subtitle::metadata::language='eng' " +
    "subtitle::font='Arial' subtitle::font_size=26 subtitle::font_color='FFFFFF' " +
    "subtitle.1::codec='dvbsub' subtitle.1::stream_id=118 subtitle.1::metadata::language='greek' " +
    "subtitle.1::font='Arial' subtitle.1::font_size=26 subtitle.1::font_color='FFFFFF' " +
    "subtitle.1::outline=true subtitle.1::outline_color='000000' subtitle.1::outline_thickness=2 " +
    "video::maxrate='5M' program::title='Medialooks subtitle test'";

MFWriterClass writer = new MFWriterClass();
writer.WriterSet(outputUrl, 1, writerConfig);

// In a processing loop:
MFFrame frame;
reader.SourceFrameGet(0, out frame, "");

writer.ReceiverFramePut(frame, 0, "");

ASS subtitle formatting

ASS subtitles support text formatting through the ASS style header. The sample exposes the main ASS formatting options in the UI.

ASS formatting is useful when the formatting should be stored directly in the subtitle file or when custom ASS styling is required. For standard output formatting, subtitle formatting can also be configured through writer properties as shown above.

The user can configure:

  • Font family
  • Font size
  • Text color
  • Outline color
  • Shadow/background color
  • Bold
  • Italic
  • Underline
  • Outline size
  • Shadow size
  • Subtitle alignment
  • Left, right, and bottom margins

Color values can be entered manually as hex values or selected through the built-in WPF color picker.

These settings are written into the ASS [V4+ Styles] section.

[Script Info]
ScriptType: v4.00+
WrapStyle: 0
ScaledBorderAndShadow: yes
YCbCr Matrix: TV.709
PlayResX: 1920
PlayResY: 1080

[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
Style: Default,Arial,26,&H00FFFFFF,&H00FFFFFF,&H00000000,&H80000000,0,0,0,0,100,100,0,0,1,2,1,2,20,20,20,1

[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
Dialogue: 0,0:00:00.00,0:00:02.50,Default,,0,0,0,,Welcome to the Example ASS Subtitle File!

When an ASS file is loaded, the sample reads the Default style from the ASS header and applies it to the formatting UI and preview.

ASS style generation example

public class SubtitleStyleSettings
{
    public string FontName { get; set; } = "Arial";
    public float FontSize { get; set; } = 26f;
    public string PrimaryColor { get; set; } = "#FFFFFF";
    public string OutlineColor { get; set; } = "#000000";
    public string BackColor { get; set; } = "#000000";
    public bool Bold { get; set; }
    public bool Italic { get; set; }
    public bool Underline { get; set; }
    public int Outline { get; set; } = 2;
    public int Shadow { get; set; } = 1;
    public int Alignment { get; set; } = 2;
    public int LeftMargin { get; set; } = 20;
    public int RightMargin { get; set; } = 20;
    public int BottomMargin { get; set; } = 20;
}

After completing these steps, the output transport stream can contain embedded bitmap DVB subtitles, DVB Teletext subtitles, or both, depending on the writer subtitle codec configuration.

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles