|
Note: This page is accurate for now, but I will probably be replacing this format with this new XML-based format (currently in draft stage).
Script files are text files which use the UTF-8 character encoding. The "Notepad" editor which comes standard with Windows 2000/XP has built-in support for UTF-8 (just select it as the encoding when you save the file), but the Notepad which comes with Windows 9x/ME does not; you will need a third-party editor if you want to use characters other than US-ASCII.
Anything within <angle brackets> in the file is a directive; anything outside of angle brackets is text to be rendered according to those directives. Newlines are not allowed inside of directives. Newlines are ignored outside of directives (they are not treated as whitespace).
Within text, a vertical bar (|) denotes a forced line break, and anything from a # to the end of the line is ignored (as a comment). If you want a literal <, |, #, or \ in your text, prefix it with a backslash (\).
Directives are case-sensitive. The directives are:
<def Macroname>...whatever...<enddef>
This directive defines a "macro," which is just a sequence of commands and/or text which gets inserted wherever you write the macro name in brackets. The example above will cause <Macroname> to be replaced with ...whatever... anywhere it appears. Don't forget to end the definition with <enddef>.
This is mostly useful for defining subtitle styles, so that you don't have to put textbox and font and color commands everywhere. See my scripts for examples.
You can't do anything fancy with macros; for example, they can't take any arguments, and you can't nest them.
<vts 02>
This indicates the DVD title set to which the subtitles will be applied. <vts 02> refers to the title set composed of VTS_02_1.VOB, VTS_02_2.VOB, and so on. It is not possible to apply subtitles to a VTS_xx_0.VOB file, or to VIDEO_TS.VOB. These files generally contain navigation menus rather than video content.
This directive must appear before any text. Even whitespace (other than newlines) counts as text, so be careful.
<angle 2>
This sets the angle to which subtitles will be applied on multi-angle titles. If it is omitted the default is angle 1. It is not currently possible to apply subtitles to all angles at once.
<textbox 0,720,0,480,2L>
This defines the area on the screen in which subsequent text will be rendered. The first four arguments are the left, right, top, and bottom of the box, in pixels. The screen resolution is 720x480 pixels for NTSC DVDs, and 720x576 for PAL DVDs. Note that the right and bottom values are exclusive, so the right-hand side of the screen is 720, not 719.
The last argument indicates how the text will be aligned inside the box. The digit at the beginning indicates how all the lines of text will be placed in the box. The letter indicates how the lines will be placed relative to each other. The possible values for the digit are 1 through 9, and denote the corresponding positions on your numeric keypad. The possible values for the letter are "L" (left), "C" (center), and "R" (right). For example, the alignment above, 2L, means that the lines of text will be left-justified relative to each other (L), and then the whole group of lines will be centered horizontally at the bottom of the box (2). This is the alignment used by AnimEigo. A more common choice is 2C, which centers each line individually at the bottom.
If the text is too wide to fit in the box, and there are no forced line breaks (|) in it, then the renderer will try to break it into two lines that are as close to equal as possible. It will not break text into three or more lines; if you want a subtitle that long you'll have to format it by hand.
If the text is still too wide to fit even after the attempt at line breaking, then you will get a warning when the script is loaded.
If you put a minus sign (-) in front of the alignment digit, then the text will be rotated 90 degrees to the right. This is useful in combination with Japanese fonts designed for vertical printing. You can use "T", "M", and "B" instead of "L", "C", and "R" for vertical text.
<at 01234,23456>
This indicates when the following text should be displayed. The first number is the first field at which the text becomes visible, and the second number is the first field at which it is no longer visible. There are about 60 NTSC fields per second, and 50 PAL fields per second. Field 0 is the beginning of the title set, but you can set a different base field with the basefield directive.
You can freely mix at directives with textbox directives. For example, if you want to display the subtitle "No, no, no!" with the three words appearing at half-second intervals, you could do something like this:
<textbox 64,656,0,440,2C> <at 12345,12465>No, <at 12375,12465> no, <at 12405,12465> no!The first "No" will appear left of center, so that when its successors appear the whole line will be properly centered.
<fadeat 123,234,345,456>
This is an alternative to at which lets you specify a fade-in and fade-out period for the text. The first number is the field at which the text first becomes faintly visible; the second number is the field at which the text becomes fully visible; the third number is the field at which the text is no longer fully visible; and the fourth number is the field at which the text is no longer visible at all.
Note that if you overuse this directive you will probably run afoul of the annoying four-color-at-once limitation of DVD subtitles. For example, you can't fade in one outlined subtitle while another is visible, because each requires two distinct colors (even if the final color is the same), and when you add the background that makes five.
<at x,y> is just a shorthand for <fadeat x,x,y,y>.
<font Arial>
<size 20>
These switch to the named typeface or pixel size for rendering subsequent text. Do not enclose the font name in quotes.
Note that pixel size is not the same as point size. Using point size in this renderer would be nonsensical because a TV image has no inherent physical size. (A point is 1/72 of an inch.)
<color FFFFF00,F000000>
This sets the color of subsequent text. The first value is the color of the text and the second is the color of the "halo" around the text. The format is similar to the six-digit system used in HTML: FFFF00 is yellow and 000000 is black, for example. But there's an extra digit at the beginning which indicates a level of transparency, with 0 being fully transparent (invisible) and F being fully opaque.
<i>
</i>
<b>
</b>
These turn italics and boldface on and off.
<linespacing -3>
By default the subtitle renderer uses the line spacing which was chosen by the font designer. This directive allows you to adjust that up or down; for example, the command above specifies a line spacing 3 pixels less than the default.
The linespacing directive takes effect with subsequent text. The actual spacing of the line will be the maximum of the spacings of all the text on that line.
<basefield 1000>
This sets the base field, which is simply an offset which is added to all the field numbers in at and fadeat directives. If omitted the default is 0, natch.
<fillbox 100,400,100,200,F000000>
This directive draws a solid-color, alpha-blended box at the indicated location, in the indicated color. Or rather, it would, if it were implemented yet. Right now it does nothing.
<on>
<off>
<off> causes subsequent text not to be rendered; <on> turns rendering on again. This is a simple mechanism for "commenting out" blocks of a script. Also, it allows for a limited form of conditional compilation; for example:
# turn this on to include extra subtitles for the hearing impaired <def HearingImpaired><off><enddef> . . . <HearingImpaired> <at 123,456><textbox ...>[Footsteps] <on>
But this requires the end-user to edit the script file, so it isn't really a very good solution.