Subtitle Format

This topic describes the DVDBuilder subtitle format.

The DVDBuilder subtitle format is based on the STL format used by Apple DVD Studio Pro. The full format is described in detail here.

Below is a description of the DVDBuilder's STL format and its usage in DVDBuilder projects.

Basic STL format

There are three parts to the DVDBuilder subtitle file: commands, comments, and entries.

  • Comments: These are preceded by a double slash (//). These allow you to add text comments throughout the subtitle file without affecting its encoding.
  • Commands: These are preceded by the dollar sign ($). It is these commands that allow you to configure the various aspects of the subtitles, such as color and opacity.
  • Entries: These include the start and end timecode values and the graphics file for that subtitle clip.

Here is an example of a typical DVDBuilder subtitle file:


// See:
// http://wiki.dvdbuilder.com/dvd-projects/subtitles/subtitle-format

// Language:  Spanish
// Subtitles: 20

// Start:     00:01:57:04
// End:       00:03:12:20

// Font:      Arial, Size: 42

// TIFF Palette
// Kind Red Green Blue Contrast
// PA 0 0 255 0 (text color - blue)
// E1 255 0 0 0 (text outer outline color - red)
// E2 0 0 0 0 (text inner outline color - black)
// BG 255 255 255 0 (background - white)

// Commands
// 

// Color
$ColorIndex1 = 1
$ColorIndex2 = 2
$ColorIndex3 = 3
$ColorIndex4 = 4

// Contrast
$TextContrast = 15
$Outline1Contrast = 15
$Outline2Contrast = 0
$BackgroundContrast = 0

// Do not force display
$ForceDisplay = False

// Entries
// 
$SetFilePathToken = <<>>

// Empty filler subtitle between start of the movie and the first real subtitle. 
// This is required by the DVDBuilder multiplexer.
// `spanish0000.tif` should be a blank image with white background
00:00:00:00 , 00:01:57:03 , <<>> spanish0000.tif

// Real subtitles
00:01:57:04 , 00:01:58:16 , <<>> spanish0001.tif
00:02:01:24 , 00:02:03:20 , <<>> spanish0002.tif
00:02:03:23 , 00:02:06:21 , <<>> spanish0003.tif
00:02:06:24 , 00:02:10:06 , <<>> spanish0004.tif
00:02:10:08 , 00:02:13:10 , <<>> spanish0005.tif
00:02:13:13 , 00:02:15:27 , <<>> spanish0006.tif
00:02:15:28 , 00:02:18:10 , <<>> spanish0007.tif
00:02:18:13 , 00:02:20:27 , <<>> spanish0008.tif
00:02:20:29 , 00:02:24:27 , <<>> spanish0009.tif
00:02:24:28 , 00:02:27:22 , <<>> spanish0010.tif
00:02:27:23 , 00:02:30:06 , <<>> spanish0011.tif
00:02:30:09 , 00:02:33:22 , <<>> spanish0012.tif
00:02:36:02 , 00:02:37:23 , <<>> spanish0013.tif
00:02:43:18 , 00:02:45:03 , <<>> spanish0014.tif
00:02:50:00 , 00:02:51:26 , <<>> spanish0015.tif
00:02:51:28 , 00:02:54:01 , <<>> spanish0016.tif
00:02:59:03 , 00:03:01:29 , <<>> spanish0017.tif
00:03:02:01 , 00:03:05:11 , <<>> spanish0018.tif
00:03:05:12 , 00:03:07:20 , <<>> spanish0019.tif
00:03:08:24 , 00:03:12:20 , <<>> spanish0020.tif

Commands

Color Commands

The following color commands choose the colors from the subpicture palette to apply to the subtitle. The values range from 0 to 15. These values map to color indexes 0 to 15 from the <subpicturePalette> element of the DVD title in which the subtitles will be used. See <subpicturePalette> Element for more details.


// The color of the text for text subtitles
// This maps to everything in the subtitle image that is in blue (RGB #0000FF).
// The default value is 1. That corresponds to DVD title's subpicture palette color with index 1. 
$ColorIndex1 = 1

// The color of the first outline for text subtitles.
// This maps to everything in the subtitle image that is in red (RGB #FF0000).
// The default value is 2. That corresponds to DVD title's subpicture palette color with index 2.
$ColorIndex2 = 2

// The color of the second outline for text subtitles
// This maps to everything in the subtitle image that is in black (RGB #000000).
// The default value is 3. That corresponds to DVD title's subpicture palette color with index 3.
$ColorIndex3 = 3

// The color of the background for text subtitles
// For image subtitles, this maps to everything in the subtitle image that is in white (RGB #FFFFFF).
// The default value is 4. That corresponds to DVD title's subpicture palette color with index 4.
$ColorIndex4 = 4

Contrast Commands

The contrast commands set the opacity of the colors assigned to the subtitle. The values range from 0 (transparent) to 15 (opaque).


// Sets the opacity of the text. The range of values is 0 to 15, where 0 is completely transparent and 15 is completely opaque.
// The default value is 15
$TextContrast = 15

// Sets the opacity of the inner outline. The range of values is 0 to 15, where 0 is completely transparent and 15 is completely opaque.
// The default value is 15
$Outline1Contrast = 15

// Sets the opacity of the outer outline. The range of values is 0 to 15, where 0 is completely transparent and 15 is completely opaque.
// The default value is 15
$Outline2Contrast = 0

// Sets the opacity of the background color. The range of values is 0 to 15, where 0 is completely transparent and 15 is completely opaque.
// This is usually set to 0, unless you are using a graphic that does not use white as the background color.
// The default value is 0
$BackgroundContrast = 0

Display Commands

These commands control how a subtitle displays.


// Forces the subtitles to display regardless of whether subtitles are turned on by the DVD player.
// You can enter True (subtitles are forced to display) or False (subtitle display is controlled by the DVD player).
// The default value is False
$ForceDisplay = False

Entries

An STL subtitle file contains subtitle entries with references to image files.

File Command

You must use the $SetFilePathToken command in the file before any lines that reference an image file.


// For example, $SetFilePathToken = <<>> would mean that a subtitle of `<<>> spanish0000.tif` would load the image `spanish0000.tif` and display that for the subtitle.
$SetFilePathToken = <<>>

Image Files

The STL subtitle file and the images it references must be in the same folder.


// You must use the $SetFilePathToken command in the file before any lines that reference a graphics file.
// For example, $SetFilePathToken = <<>> would mean that a subtitle that references `<<>> spanish0000.tif` would load the image `spanish0000.tif` and display that for the subtitle.
$SetFilePathToken = <<>>

// Entries

// Empty filler subtitle between start of the movie and the first real subtitle. 
// This is required by the DVDBuilder multiplexer.
// `spanish0000.tif` should be a blank image with white background
00:00:00:00 , 00:01:57:03 , <<>> spanish0000.tif

// Real subtitles start here
00:01:57:04 , 00:01:58:16 , <<>> spanish0001.tif
00:02:01:24 , 00:02:03:20 , <<>> spanish0002.tif
00:02:03:23 , 00:02:06:21 , <<>> spanish0003.tif
00:02:06:24 , 00:02:10:06 , <<>> spanish0004.tif
00:02:10:08 , 00:02:13:10 , <<>> spanish0005.tif
00:02:13:13 , 00:02:15:27 , <<>> spanish0006.tif
00:02:15:28 , 00:02:18:10 , <<>> spanish0007.tif
00:02:18:13 , 00:02:20:27 , <<>> spanish0008.tif
00:02:20:29 , 00:02:24:27 , <<>> spanish0009.tif
00:02:24:28 , 00:02:27:22 , <<>> spanish0010.tif
00:02:27:23 , 00:02:30:06 , <<>> spanish0011.tif
00:02:30:09 , 00:02:33:22 , <<>> spanish0012.tif
00:02:36:02 , 00:02:37:23 , <<>> spanish0013.tif
00:02:43:18 , 00:02:45:03 , <<>> spanish0014.tif
00:02:50:00 , 00:02:51:26 , <<>> spanish0015.tif
00:02:51:28 , 00:02:54:01 , <<>> spanish0016.tif
00:02:59:03 , 00:03:01:29 , <<>> spanish0017.tif
00:03:02:01 , 00:03:05:11 , <<>> spanish0018.tif
00:03:05:12 , 00:03:07:20 , <<>> spanish0019.tif
00:03:08:24 , 00:03:12:20 , <<>> spanish0020.tif

Graphics Files

DVDBuilder does not generate the subtitle image. You need to generate the images in your code. We describe here some guidelines for the subtitle images.

General Requirements

Subtitle images must be uncompressed graphic files in Windows Bitmap (extension .bmp), or TIFF (.tif) format.

The images must use only these four colors:

  • pure blue (RGB 0, 0, 255) - text
  • pure red (RGB 255, 0, 0) - text outline 1
  • pure black (RGB 0, 0, 0) - text outline 2
  • pure white (RGB 255, 255, 255) - background

Blue will be mapped to the Text parameter for colors and contrasts, red will be mapped to Outline1, black to Outline2, and white to Background. If an image is smaller than the screen size, areas beyond the edge of the image will be treated as if they were in the Background color.

Image size must be the same size as the resolution used in the <videoObject> element, e.g. NTSC 720x480 or PAL 720x576 or another supported resolution. See <videoObject> Element for more details.

Text requirements

When creating subtitle images you need to keep the title-safe area in mind to handle televisions that cut off the edges. The title-safe area is 72 pixels in horizontally for NTSC and PAL, and 48 pixels in vertically for NTSC, 58 pixels in vertically for PAL.


Last updated on November 10th, 2017 12:00:00 AM