Spruce Subtitle Format

The Wayback Machine - https://web.archive.org/web/20091028173024/http://geocities.com/McPoodle43/DVDMaestro/stl_format.html

Spruce Subtitle Format

The Spruce Subtitle format (extension .stl) was designed specifically for DVDMaestro, and is capable of implementing all of DVDMaestro's subtitle features, with the following exceptions, which must be set in DVDMaestro after the subtitles are imported:

The language code of the subtitles.
Interactive subtitles (specifically, the button areas, navigation, the color maps, and the marker that transforms an ordinary subtitle into an interactive subtitle; note that you can include all the other parts of an interactive subtitle in the STL file and then transform it after it is imported).
Stream mapping. This obscure but ingenious DVDMaestro feature allows you to force different subtitle streams based on how 16:9 video is shown to the user, resulting in subtitles that play over the video for users with widescreen televisions and over the black bar for users with square televisions watching the video letterboxed.

Here is a sample Spruce Subtitle file (subtitle_en.stl):

//English subtitles
$FontName           = Arial
$FontSize           = 36
$HorzAlign          = Center
$VertAlign          = Bottom
$XOffset            = 0
$YOffset            = 0
$ColorIndex1        = 0
$ColorIndex2        = 2
$ColorIndex3        = 8
$ColorIndex4        = 3
$Contrast1          = 15
$Contrast2          = 0
$Contrast3          = 15
$Contrast4          = 0
$ForceDisplay       = FALSE
$FadeIn             = 3
$FadeOut            = 7
$TapeOffset         = FALSE

00:00:03:24 , 00:00:06:29 , Did you read the paper today?
00:00:10:07 , 00:00:12:21 , No, did Edwards quote me right?
00:00:14:19 , 00:00:25:28 , Actually, ^IBrillstein^I said you were | unimaginably full of yourself.

Lines will be treated as comments if there are "//" characters in columns 1 and 2. The file has two types of lines: control commands and subtitles.

Control commands consist of a command, the = character, and a value. Control commands can occur at the beginning of the file or anytime the value of the command needs to change. Commands and values are case-insensitive.

Here is the list of commands:

$FontName: Name of the font to render the subtitles in. The font must be installed on the computer running DVDMaestro.
$FontSize: The font size, in points.
$Bold: If value is TRUE or 1, this puts all of the following subtitles in bold text. If value is FALSE or 0, sets the subtitles to normal text (this is the default value for when $Bold is not in the file). The $Bold control command can be overridden in the text with the control code ^B.
$UnderLined: Sets or removes underlines for the following subtitles. Overridden by the control code ^U.
$Italic: Sets or removes italics for the following subtitles. Overridden by the control code ^I. Note that all three of these commands can be applied at the same time.
$HorzAlign: Sets the horizontal alignment of the following subtitles. Possible values are Left, Center, and Right. Note that the Left and Right values will not put the text against the edge of the image, but at the edge of the title-safe area (72 pixels in), to handle televisions that cut off the edges.
$VertAlign: Sets the vertical alignment of the following subtitles. Possible values are Top, Center, and Bottom. Note that the Top and Bottom values not put the text against the edge of the image, but at the edge of the title-safe area (48 pixels in for NTSC, 58 pixels in for PAL), to handle televisions that cut off the edges.
$XOffset: Moves the following subtitles over horizontally. The values are in pixels. Positive values shift the text to the right, while negative values shift the text to the left. Be aware that DVDMaestro will not automatically wrap lines, so if you're not careful, your subtitles could go beyond the title-safe area or even beyond the edge of the image.
$YOffset: Moves the following subtitles over vertically. The values are in pixels. Positive values shift the text downwards, while negative values shift the text upward. Note that changing $XOffset and $YOffset for each subtitle while using extremely short durations (as short as 1 or 2 frames) can be used to create animated subtitles. This technique is very resource-intensive, not only on DVDMaestro when compiling the DVD, but also on the settop player or PC player program that tries to render it.

$ColorIndex1: Sets the palette entry for Color1. For text subtitles, Color1 is the color of an outline around the text ("Outline 1" in DVDMaestro). For image subtitles, Color1 maps to everything in red (255, 0, 0 in Red, Green, Blue format). The default value is 0. The 16-color palette can be set up in DVDMaestro just before importing the STL script, and it can also be saved and loaded for standardization. The default palatte is as follows (with color values in RGB format):

0

000, 000, 000

Black

1

032, 032, 032

Off-Black

2

255, 255, 255

White

3

255, 000, 000

Red

4

128, 128, 128

Gray

5

192, 192, 192

Silver

6

000, 255, 255

Aqua

7

255, 000, 255

Fuschia

8

255, 255, 000

Yellow

9

000, 000, 128

Navy

10

000, 128, 000

Green

11

128, 000, 000

Maroon

12

000, 128, 128

Teal

13

128, 000, 128

Purple

14

128, 128, 000

Olive

15

255, 255, 255

White

$ColorIndex2: Sets the palette entry for Color2, the color of an outer outline outside Outline 1 for text subtitles (called "Outline 2" in DVDMaestro), and the color map for black (0, 0, 0) in image subtitles. The default value is 1.
$ColorIndex3: Sets the palette entry for Color3, the color of the text for text subtitles, and the color map for blue (0, 0, 255) in image subtitles. The default value is 2.
$ColorIndex4: Sets the palette entry for Color4, the color of the background for text subtitles, and the color map for white (255, 255, 255) in image subtitles. The default value is 3.
$Contrast1: Sets the opaqueness of the inner outline. The range of values is 0 to 15, where 0 is completely transparent and 15 is completely opaque.
$Contrast2: Sets the opaqueness of the outer outline. This is usually set to 0 so it isn't seen.
$Contrast3: Sets the opaqueness of the text.
$Contrast4: Sets the opaqueness of the background. Setting this to any value other than 0 will make the video behind the subtitle hard to see.
$ForceDisplay: Setting this control command to TRUE or 1 will cause the following subtitles to display regardless of the DVD player setting. This is used mainly to provide the viewer with a translation when some of the dialog is in a different language than the rest of the soundtrack. The default value of this control command is FALSE.
$FadeIn: Sets how long the following subtitles will take to fade in from transparency, in frames. Since there are only 15 opacity levels, you will get a visible "stepping" effect if you use values greater than around 20. A value of 0 (or not including the control command in the script) will cause the subtitles to appear without fading in.
$FadeOut: Sets how long the following subtitles will take to fade out to transparency. Note that both fade-in and fade-out occur within the times given for the subtitle.
$TapeOffset: Setting this to FALSE or 0 will cause the subtitle times to be calculated from the beginning of the video track. The default value of TRUE sets the times based on the internal timecodes in the MPEG-2 video.
$SetFilePathToken: This is a text string used to identify when a subtitle is an image rather than text. For example, $SetFilePathToken = ((image)) would mean that a subtitle of StreetSign03.gif would print that text on the screen, while a subtitle of ((image)) StreetSign03.gif would load the graphic StreetSign03.gif and display that for the subtitle.
$SetWipeColor1: Sets the first of four colors available for Karaoke wipes of the subtitle (where the text changes from one color to another as each word is to be sung). The value is a color in red,green,blue format (for example, 255,255,0 would give you yellow).
$SetWipeColor2: Sets the second Karaoke wipe color, in red,green,blue format.
$SetWipeColor3: Sets the third Karaoke wipe color, in red,green,blue format.
$SetWipeColor4: Sets the fourth Karaoke wipe color, in red,green,blue format. A maximum of one set of wipe color control commands is allowed in a script (if more than one is found, only the last set will be used for all subtitles using wipes).
$WipeTextColor: Specifies which of the four wipe colors will be used for the text after it has been wiped. The possible values are 1, 2, 3, or 4.
$WipeOutline1Color: Specifies which wipe color will be used for the inner text outline after it has been wiped.
$WipeOutline2Color: Specifies which wipe color will be used for the outer text outline after it has been wiped.
$WipeBackgroundColor: Specifies which wipe color will be used for the background of the wipe rectangle, after it has been wiped. Note that unlike the $SetWipeColor control commands, $WipeColor control commands can occur multiple times in the same shift, to shuffle the four available colors between Text, Outline1, Outline2, and Background.
$WipeTextContrast: Sets the opacity of the text after the wipe. Values are from 0 to 15.
$WipeOutline1Contrast: Sets the opacity of the inner outline after the wipe.
$WipeOutline2Contrast: Sets the opacity of the outer outline after the wipe.
$WipeBackgroundContrast: Sets the opacity of the background of the wipe rectangle after the wipe.

The subtitle itself consists of the following comma-separated fields:

Start Timecode: This is the timecode when the subtitle starts displaying, in SMPTE format (hours:minutes:seconds:frames). If $FadeIn is set, it will start from this time.
End Timecode: This is the timecode when the subtitle will stop displaying, in SMPTE format. If $FadeOut is set, it will end at this time.
Subtitle: This is the text of the subtitle to display. The following special characters are recognized:
- |: This character forces a line break at the position given. For multi-line subtitles, the alignment settings are applied to the entire subtitle, i.e. if $VertAlign is Bottom and $YOffset is -25, then it will be the bottom of the last line of the subtitle that will be located 25 pixels from the bottom of the screen, while if $VertAlign was Top, it would be the top of the top line that the offset would be measured against.
- ^B: Toggles boldface on or off. If $Bold has been set to TRUE, then the first appearance of ^B will turn boldface off.
- ^U: Toggles underlining on or off.
- ^I: Toggles italics on or off. Note that any combination of boldface, underlining, and italics can be applied at once.
If the subtitle begins with the string defined by $SetFilePathToken, the following text will be interpreted as the name of an image file to display. If the image is not located in the same directory as the script file, it will need to be proceeded by the absolute path, for example D:\Subtitles\Bitmaps\StreetSign03.gif. The image needs to be an uncompressed graphic file in Windows Bitmap (extension .bmp), GIF (.gif), JPEG (.jpg), or TIFF (.tif) format. It must use only four colors: pure white (RGB 255, 255, 255), pure black (0, 0, 0), pure red (255, 0, 0), and pure blue (0, 0, 255). 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 the 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. The following control commands do not apply to images: $FontName, $FontSize, $Bold, $Underline, $Italic, $HorzAlign (forced to Top), and $VertAlign (forced to Left).

For the special situation of Karaoke wipes, the following must appear in the lines after the text:

First line: {. This character on a line by itself establishes that a special function will follow (wiping is the only special function so far in STL format).
Subsequent lines: WipeInfo:, followed by these comma-separated wipe parameters:
- Start Offset: This parameter sets when the wipe begins. The value is the number of frames after the subtitle appeared.
- Wipe Rectangle Coordinates: These four parameters set up the rectangle within which the wipe will take place (in left, upper, right, lower order). The values are in pixels and are relative to the upper-left corner of the screen, not the subtitle, meaning it is very easy to accidentally place the wipe rectangle entirely outside the subtitle, resulting in an invisible wipe (unless $WipeBackgroundContrast has been set to something other than 0).
- Wipe Duration: This parameter sets how long this wipe will last.
- Wipe Sense: This parameter sets whether the wipe will change the original subtitle colors into the wipe colors (a value of 0), or if it will change the wipe colors into the original colors (a value of 1).
- Wipe Start: This parameter sets which edge of the wipe rectangle the wipe will begin with: Left, Right, Top, or Bottom. The wipe will proceed to the opposite side of the rectangle.
- Wipe Limits: These two parameters set off areas at either end of the wipe rectangle that will not be included in the wipe. If Wipe Start is Left or Right, the Wipe Limits will be left and right values relative to the screen's upper-left corner, while if the Wipe Start is Top or Bottom, the Wipe Limits will be top and bottom values relative to the screen's upper-right corner.
There is usually one WipeInfo line for each word in the subtitle. It is possible to have multiple wipes in different directions going at once.
Last line: }. This character on a line by itself ends the special function.