JACOsub Script File Format Specification

Here is the complete JACOsub script file format specification. It's not complicated (unless you want it to be) and quite flexible. Check out the sample script (demo.jss) that came with this software; it demonstrates many of the things you can do with a script.

Basic format conventions
Compiler commands
Timed lines
Directives (for controlling timed lines)
Sample lines
Credits

Most of the information in this document is demonstrated by the timed script demo.jss, which is included in the JACOsub distribution archive.

1. BASIC FORMAT CONVENTIONS

Space characters (white space) may consist of spaces or tabs. Any line in a script file may contain any amount of white space in front of, behind, or in between parameters or words.
A line cannot be more than 511 characters in length (but you can concatenate several lines; see Escape Codes below).
Lines in the file may be blank lines, compiler commands, or timed lines for the script. All these are explained below.
Blank lines or lines containing white space only are ignored.

2. COMPILER COMMANDS

Any line where # is the first non-space character is treated as a compiler command. The command is indicated by the next character or word (upper or lowercase) following the #. Some commands have arguments, which are assumed to begin with the next non-whitespace characters following the command. Anything shown here in square brackets [ ] are optional. The commands are:

# (followed by a space)

Comment. The line will be ignored.

Example:
# This is a comment.

#C[LOCKPAUSE] <time>

While a script is running, this command forces the clock to pause the clock at the time specified by <time>. Pressing a key will resume play. <time> is an offset from the beginning of the script in the form H:MM:SS.FF (hours:minutes:seconds.units). The beginning time of a script is usually 0:00:00.00 unless the script was included with an offset using the #I command.

This command is useful for titling multiple laserdisc sides in a single script. Be warned: There will be no indication on the screen telling you that the script is paused! You have to keep track of your pauses yourself.

#D[IRECTIVE][n] <directive string> [optional_name]

Change some directive defaults (see the DIRECTIVES section below), for example:

#D CF10F2 small_red_text #directive3 hr50vmf2 #d9JLJBC

This command affects only those lines following it. Scripts may contain as many #D commands as you like.

There are 31 default directives available, D0 through D30. Specifying #D is the same as #D0 -- this sets the general overall default directive when a title line contains no directive or when just the D directive is present. The directives D1 - D30 may be set for situations when you need a shorthand way to represent a long complicated directive string in many places in your script. Directives D0-D30 are initially all identical, according to your DIRECTIVE config setting.

Instead of a long cryptic directive in your timed lines, you may use the short codes you define, like D, D1, D2, etc. Alterately, you may also assign sensible names to your directive definitions and use these names instead of the codes D3, D4, etc. If you use a directive name instead of the actual directive code in your title, you must enclose the name in square brackets []. The name definition in the #D command must NOT contain brackets. The name will be truncated after 20 characters, and uppercase or lowercase doesn't matter.

#F[ONT] <n> <fontname.font> <size> [CLEAN or QUICK&DIRTY] [Y/X]

This command sets font <n> to <fontname.font> which is <size> pixels high. Font settings affect the entire script. The <n> argument may range from 0 to 9. #F commands should be specified before any timed lines in the script.

CLEAN or QUICK&DIRTY indicate the rendering mode for the font. Normally, you should NEVER need to set the rendering mode! The program is smart enough to determine the best mode. Mono-color fonts will always be QUICK&DIRTY, and color fonts will be CLEAN only if the characters are designed to overlap.

The rest of the arguments apply to the Amiga only:

The Y/X argument modifies the default 1/1 aspect ratio for the font's height vs. width. It must be specified as two integers separated by a slash with no spaces, as in 40/33. This argument works only in AmigaDOS versions 2.0 or higher.

NOTE: Due to the Amiga's internal font management, the Y/X parameter will affect only those fonts having names and/or sizes different from those fonts already loaded in memory. For example, the 36-pixel JACOsub font is loaded as font 0 when the program starts up, and its aspect ratio will be whatever it had when it loaded (see the FONT setting in the jacosub.cfg file). Any attempt to assign "jacosub.font 36" a different aspect will have no effect. You can get around this by setting the program configuration so that font 0 is something like Topaz 9, rebooting, and then using your script to load jacosub.font 36 with the desired aspect ratio.

Example:
#F 2 Diamond.font 20

#H[RES] <resolution mode>

This sets the horizontal display resolution mode (HIRES or SUPERHIRES) that is expected to be used with the script. This should be set in the program configuration; set it in the script ONLY if the script is designed specifically for a particular resolution mode. SUPERHIRES will be ignored on computers incapable of it. This command will be ignored if it occurs after the first timed line, or inside #Included scripts.

On Amigas, a typical HIRES mode is 640x400. A typical SUPERHIRES mode is 1280x400. Under MSDOS, HIRES is 640x400, and SUPERHIRES is 800x600.

#I[NCLUDE] <time> <filename>

Include another script file <filename> into the current script, offsetting the second script's start time by <time>. <time> is always FORWARD offset.

This command is useful, for example, if you are subtitling a series of TV shows having subtitles for credits and ending song lyrics. Rather than importing and/or re-timing the same sequences over and over again for each episode, you need only time the song lyrics once and the credits once, with the times starting at zero, and save these two scripts as separate files. When your "main" script includes these other scripts, they will be incorporated properly into the main script to start at the proper time (which is <time> added to the first time event in the included script), and any overlapping time ranges will be interwoven properly.

<time> is specified in the form H:MM:SS.FF, where H is an hours digit, M is a minutes digit, S is a seconds digit, and F is a fractional-second digit. The units of F are determined by the #T command (below), and default to 30 units/second if the #T command was omitted (that is, the FF digits are SMPTE units ranging from 00 to 29). The included script may in turn contain its own, possibly different, #T command, and also its own #I commands. <time> always offsets the "includee" relative to the beginning of the "includer," taking into account the "includer's" own offset if the "includer" was itself included by some other script.

<filename> may be any valid path + file name. <filename> can specify a complete path; if no path is specified then JACOsub will look in the default scripts directory, which you can set in the General Config menu. If you omit the extension in <filename>, then the program will include the script with the most recent time-stamp, among the extensions .jss, .tts, .pjs, or .tim (.jsc, .pan, or .sub files won't be considered). The file name must not contain any spaces.

Any occurrences of #F, #P, #Q, and #R in an included script will be ignored. These commands work only in the primary script, and they affect all included scripts. The effects of #D, #S, and #T commands are passed down into included scripts, but these commands inside an included script affect only that script and others IT might include; they have no effect on the higher-up "calling" scripts.

Example:
#I 0:21:44.16 scripts:kor/kor-credits.jss

#P[ALETTE] <color> <r> <g> <b> [palette]

This sets the red, green, and blue intensities for color register <color> (0-15), to <r>, <g>, and <b>, respectively. RGB intensities may be specified in decimal (0 to 15) or hexadecimal (0 to f). If any of the values <r>, <g>, or <b> are 16 or higher, the palette specification is assumed to be 24-bit (i.e. RGB intensities from 0 to 255 decimal, or 00 to ff hexadecimal). Hex numbers may be upper or lowercase.

#PALETTE may be specified anywhere in the file, but the setting will be used for the entire script. Use RGB values 14 or higher (24-bit: 238 dec, EE hex) with caution, as these are stronger than normal video signals, and can result in color bleeding when using in your genlocked video signal.

Do not redefine color 2; JACOsub expects it to remain black.

The optional [palette] parameter defaults to 0, and indicates the palette number in which to set the color. JACOsub has 10 palettes available. All 10 palettes are initialized to initial values set in the Playing / video Config menu. Palettes 1 - 9 may be used to reset temporarily certain colors for a particular display, using the CP directive. If JACOsub is using a 2-bitplane display, for example, you are restricted to 4 colors at any one time, but using multiple palettes allows you to redefine them on the fly.

Examples:
#P1 14 14 6 # set color 1 to yellow in default palette 0 #P1 d d 6 # same as above, using hexadecimal RGB values #p 3 0 13 0 1 # set color 3 to green, in palette 1

#Q[UANTIZE] [n]

This command has the effect of eliminating timing gaps between subtitles of less than [n] time units, as specified by the #T command. Default is #Q0. Example: With #t30 and #q2 specified, any time event less than 2/30 seconds earlier than another time event will be rounded up to the later event. This is of questionable usefulness. If this command occurs before a #T command, then 30 units per second is assumed. Subsequent #Q commands replace earlier ones. Only the last #Q command in a script has any effect.

#R[AMP] <seconds.units>

If you play a pre-timed script, and discover a time drift, then use this command. The parameter <seconds.units> is the amount of drift to correct over the entire script. Script timings will be adjusted appropriately according to this value. A positive value will lengthen the total script running time, and a negative value will shorten the total script running time. The default value is #R0. The number after the decimal point is NOT a fractional second; it is the number of time units specified by #T. THIS COMMAND MUST NOT OCCUR BEFORE A #T COMMAND. Examples:

#R-3.60 (shorten the script running time 3 seconds plus 60 time units) #R .92 (lengthen the script running time 92 time units.)

IMPORTANT: Genlocks may affect the computer's internal clock. If you find that you have to ramp a 30-minute script more than 10 seconds, then you have a bad problem with your genlock. DO NOT TRY TO "FIX" THE PROBLEM WITH A BIGGER RAMP TIME! Doing so will result in math overflows, causing sudden jumps in timing.

#S[HIFT] <[[hours:]minutes:]seconds.units>

The parameter <seconds.units> is the amount to shift each time event in the script. A positive value will delay each time, and a negative value will advance each time. The default value is #S0. The number after the decimal point is NOT a fractional second; it is the number of time units specified by #T. THIS COMMAND MUST NOT OCCUR BEFORE A #T COMMAND.

The first occurrence of #S in a script determines a global amount of shift, even if the first #S appears AFTER some timed lines. Subsequent occurrences affect only those lines following the #S. You must take care that your #S commands do not cause any times to be less than zero. The Amiga uses unsigned integers (always positive) for its internal representation of times, meaning that a time "less than" zero is actually a very large number!

Example:
#S -0.20 will cause ALL events to occur 20 time units sooner than usual, if this is the FIRST #S. Otherwise, all events SUBSEQUENT to this command will be shifted so that they occur 20 units sooner.

#T[IMERES] <n>

Time resolution; sets time units to <n> per second. The default is SMPTE units of 30 counts/second, as in #T30. If your script is in units 1/100 second units or PAL units, you must say so with the appropriate command, before the subtitle text begins. The #R or #S commands cannot precede a #T command.

Examples:
#t100 #TIMERES 25

3. TIMED LINES

Timed lines for the script may occur in any order. They look similar to this:

H:MM:SS.FF H:MM:SS.FF directive {comment} text {comment} more text...

For example:

0:30:57.22 0:30:59:46 vm {opening credit} A Film By Akira Kurosawa

Here's what all those pieces are:

Start time and stop time

The first field is the time when the subtitle is to appear on the screen. The normal default is SMPTE format (that is, FF can range from 00 to 29). Use the #T command (described above) to define the units. IMPORTANT: The FF digits represent time units, NOT fractions of a second. There is a difference! For example, if you use #T10 to specify 1/10 second time units, then a time such as 0:00:00.60 would be illegal (and result in an error) because it specifies 60 time units! 0:00:00.6 or 0:00:00.06 or even 0:00:00.00006 would be correct for this case -- 6 UNITS are specified, not 6 tenths of a second.

The second field is the time when the title is to disappear.

If you prefer, you do not have to use the H:MM:SS.FF format at all. Instead, you can substitute a @ symbol followed by a single integer to represent total time units. For example, if #T30 is used to specify 1/30 second units, then the 0:05:10.22 is the same as @9322. This format is useful for representing times as video frame counts. Many laserdisc players display times in this fashion.

Directive string

The next field is the directive. It is optional. If you leave it out, the program will default to standard subtitling form (all text centered at the bottom of the screen or depending on how you have your global default directive set in your configuration). The title text MUST begin with a non-alphabet character {such as a comment} if you omit the directive. Directives are explained fully in the DIRECTIVES section below. The first non-whitespace character following the directive is assumed to be the beginning of the subtitle text.

Inline comments

The {comment} is considered a part of the subtitle text, but it is ignored by the software. Use it for character names or keywords. A comment must be enclosed in braces. Comments may appear anywhere within the text of a subtitle. If you really want to to display a left brace, precede it with a backslash like so: \{. Right braces will be interpreted as a literal character or close of a comment, whichever seems appropriate. If a whitespace character immediately follows a comment closing brace, then that first whitespace character will be ignored. Any other kind of following character will be considered part of the subtitle text, and used. Comments in the text are especially useful when translating foreign films -- we use them to list possible translations of phrases we are not yet sure about.

Title text and escape codes

In the example above, the "text" and "more text" fields are what get displayed. There are several special codes that you can put inside the text (in JACOsub scripts, CASE MATTERS ONLY IN THESE CHARACTER CODES):

Special character codes:

\: Concatenate. If the LAST character in a line is a backslash, then JACOsub will concatenate the text on the next line to the text in the current line. Leading and trailing whitespace will be stripped from the concatenated text, so you can indent it if you wish.
\n: Newline. This is like a carriage return. A line containing this code will be split at the \n. Each of these new fragments will then be wordwrapped separately unless you turn wordwrapping off (see the W directive below). \n is useful for general formatting. Multiple \n codes may be concatenated to create blank lines. Example: Hello!\n\nHow are you?{blank line separating the two}
\{: Display a left brace. Left braces are normally used to indicate the beginning of a comment.
\~: Display a tilde. Tildes are normally used to create "hard" spaces (see below).
\\: Display a backslash. Backslashes are normally used to denote these special codes.

Insertions:

\D: Insert current date into the title. The date will be of the format DD MMM YYYY, as in 2 Apr 1996.
\T: Insert current time into the title. The time will appear as HH:MM (24-hour time).

Font codes:

\N: Normal. All text appearing after this code will be displayed in "normal" style. This is typically the default, unless you have the style (S) directive set to something other than normal. Note that this code is an uppercase \N -- a lowercase \n is a newline code.
\I: Italics. Display all text appearing after this code in italics. Example: \IHello!\N\nHow are you?{Hello is in italics}
\i: Italics off. Turn off italics, leaving other attributes (like boldface) alone. \N, on the other hand, turns off all attributes.
\B: Boldface. This one isn't particularly useful, but go ahead if you feel like it. Text characters will be slightly fatter.
\b: Boldface off.
\U: Underline. This is virtually useless for large color text.
\u: Underline off.
\Cn: Color n. The text following this code will be displayed using face color n. n is a hexadecimal digit; it may take the values 0-9 or A-F (or a-f). Typically, when using the font supplied with this software on a 2-bitplane display, only colors 3 and 1 are useful. See the CF directive below for some caveats about colors.
\Fn: Font n. The text following this code will be displayed using font number n. n may range from 0 to 9. Normally you would use the F directive to set the default font for a line; use this escape code to override it.

THE FONT CODES ABOVE AFFECT ONLY ONE TIMING LINE; their effects do not carry over into other lines. These codes override any directives. The \I, \B, and \U codes may be combined: You can have bold text or italic text, or BOTH bold and italic. See the demo script file (demo.jss) for good examples on usage.

Leading or trailing space in subtitle text will be ignored. If you want to encode a true space on the ends of some text, use a tilde (~). It will be displayed as a space. To actually display a tilde, precede it with a backslash: \~. Tildes may also be used to create "hard" spaces; they will be displayed as spaces but text will not be wordwrapped on these spaces.

White space between line arguments may consist of any amount of spaces or tabs. Each tab character inside the subtitle text will be converted to a space character.

4. DIRECTIVES

Directive strings were briefly described above, but there are so many that they deserve to be allocated a whole section of this document.

A directive is a series of character codes strung together. A directive determines a subtitle's position, font, style, color, and so forth. Each character code begins with an alphabet character followed by arguments made up of other alphabet characters and numbers. Directives may contain any of the following codes, in any order. The directives may be uppercase or lowercase. Like the text codes above, directives only affect a SINGLE timing line; their effects do not carry over into other lines. Any parameters shown here in square brackets [] are optional.

Vertical positioning

VA

Continue this line directly Above the previous one. This is the opposite behavior of VU below. This is a useful directive for those cases where you want a new line to appear above the previous line's position, even if both lines do not share the same time range. See VU below for more details.

VB[n]

Bottom. Position last line at the bottom (default). The offset from the bottom of screen n is optional - it says how many raster lines to offset from the physical bottom-of-viewport. VB by itself is the same as VB16 (in the original default for this software). The default value of n can be changed using #D command or in the General Configuration settings.

VHn

Line height (i.e. spacing), where n is the percentage of the font height to use for line spacing. Default is 100 (single- spaced). Using 200 would result in double-spaced lines. n may range from -32768 to 32767, although the useful range is probably more like 50 to 500.

VL[n]

line n. Position subtitle starting at text line n (the height of a line depends on the font you use). n=0 is the top line. If n is negative or omitted, the line will appear in the same vertical position as the preceding timed line.

VM[n]

Middle. Text will be centered vertically in the area defined by the VTn and VBn directives. The optional parameter [n] is a positive or negative integer that will cause the centered block to be shifted up or down [n] lines (line height determined by the VH setting).

VPn

Pixel n. Position subtitle so that the font baseline of the first line of text is n pixels from the top of the viewport. You need to know your font's baseline position for this directive to be of any use. The mouse-positioning operation in the script editor creates directives like this.

VS[n] (Amiga)

Scroll at speed n (default -2). n<0 is number of frames to wait per raster line scrolled. n>0 is number of raster lines to scroll per frame. n may range from -6 to 4, with the values -1, 0, and 1 all treated the same. Text will scroll in from the bottom of the display and scroll off the top. If the start time of scrolled text is the same as the end time of the previous view, the previous view will be scrolled off as the new text is scrolled in. The new text to be scrolled in will begin at an offset below the bottom edge of the screen, controlled by the VT offset quantity.

Important considerations for vertical scrolling directive:

Overlapping time ranges are ignored, except for concatenations caused by VU directives. Use the VU directive to concatenate title paragraphs, otherwise use the end-of-line concatenation escape character (\).
Be sure you give the titles sufficient duration for the scrolling to complete -- if the duration is too short, scrolling will complete anyway, delaying anything scheduled to happen immediately afterward.
The only really useful scrolling speeds are -2 or less. Speeds of 2 or higher are almost too fast to read anything, and the maximum speed of 4 is usually too fast for the program to keep up with. Speeds -1, 0, and 1 (all treated the same) result in strange distortions due to the fact that the video is interlaced. This fact, combined with an odd- numbered scroll at every video refresh, causes only every other line in the bitmap to be visible during the scroll.
Regardless of whether the speed is even or odd, positive speeds that do not divide evenly into your screen height will be reduced to the next lower speed that does divide evenly.
The following directive prefixes will be ignored: E, CS, FC, FD, FO, FS, FQ, I, and R.
Scrolling may not be smooth for large fonts or color fonts, or it may be smooth but the text may not be generated rapidly enough to keep up with the scroll. Either way, the program will warn you if you try to scroll a color font. It works best with small-to-medium sized mono-color fonts.
Under AmigaDOS 1.3 and below, fonts with slightly overlapping bitmaps may not be spaced properly. The program will warn you of this if you try it under 1.3.
The VU directive may be used after VS to append more text. You should use VU to concatenate paragraphs of scrolling titles. This is more memory-efficient than using the \ concatenation code at the end of each line.
You can use embedded codes to change text style and color, but be careful changing fonts in the middle of a line. Changing fonts works best if the new font is on a separate line all its own, or if the new font is the same size as other fonts on the same line.
This directive uses a significant amount of display memory; equivalent to slightly more than two additional display buffers. Insufficient RAM will cause scrolled titles to be skipped. Sometimes the scrolling bitmap will fail to allocate from fragmentation in the available display memory. Shutting down the program and restarting it might alleviate this fragmentation enough to facilitate scrolling.

VT[n]

Top. Position the title with the first line at the top. The offset n is optional - as with VB, VT by itself is the same as VT16 in the original distribution of this software.

VU

Continue this line directly Underneath the previous one. This is useful if you want a line with different directives grouped in the same vertical-positioning block as the previous line. It's like the line-concatenation escape code (\) only it doesn't continue the previous line where it left off, but instead starts a new line below it, positioning the previous line higher, if necessary, to make room for the new line.

You can also use the VU directive to create interesting effects when a line with the VU directive does not share the same time range as the previous line. For example, suppose you had a single line that used the VM directive. Normally it would be perfectly centered vertically on the screen. However, if a VU line follows it, both are positioned as if they were a single block of lines to be centered on the screen together; i.e. the VM line will appear slightly above center and the VU line will appear slightly below center, regardless of WHEN they are individually displayed. Had VB been used instead of VM, the first line would have appeared raised one text line higher than bottom, just enough to make room for the second line. VA has the same effect as VU if the lines are reverse-ordered in the script.

Horizontal positioning

[Margins]

HLn

Left margin. Set left margin at a position that is n% of the the screen width. Default is HL1 (1% from left edge). Minimum value is -128 (way past the left edge of the display area).

HRn

Right margin. Set the right margin at a position that is n% of the screen width. Default is HL99 (1% from right edge). The right margin MUST be greater than the left margin. Maximum value is 127, although anything greater than 100 is useless.

[Text justification]

JC

Center. Text is centered within H constraints (normal default).

JF[:p]

Full. This aligns the left and right edges of text flush with the ends of the widest wordwrapped line in the text block. If you want the justified text to span the full margin width, set wordwrapping to W2 (greedy) instead of W1 (smart, the default). The :p is a position parameter. It may be :C (default), :L, :R, or :U, for Center, Left, Right, and Unconditional, respectively. :C, :L, and :R control the position of non-wordwrapped lines such as single short lines or the last line in a wordwrapped block -- these will not not be stretched to fit the block width.

(Remember, \n codes delimit wordwrapped blocks; a title split by \n codes will wrap and justify each section as if they are completely separate titles. If you want to justify a title properly, you should remove all \n codes except for where the wrapping and justifying should end.)

The :U parameter means "unconditional." JF:U is the same as JU. JF:U causes ALL lines in the block, wordwrapped or not, including the last line, to be stretched to fit exactly within the margins. JF:U is useful for titling credits like this:

Clint Eastwood . . . . . . . Dirty Harry

All the spaces will then be adjusted so that the line fits exactly inside the margins, and a list of these credits will have flush left and right edges. You will need to experiment with the number of dots and spaces to get it all to look good. You can also try elminating the spaces between the dots, or substituting dashes, for somewhat different effects.

JF[:p] commandeers one character in each proportional font for use as an adjustable space; the decimal character code used will be one of: 128, 31, or 127, whichever is available (hex codes 80, 1F, or 7F, respectively). The JF directive has no effect on fonts lacking all of these character codes. Mono-spaced fonts are likewise unaffected.

JL

Left. Align left edge of text at the HLn margin position.

JR

Right. Align the right edge of text at the HRn margin position.

JU

Obsolete directive; identical to JF:U

[Block justification]

JBC

Justify block center. Because of wordwrapping, the width of a text block will never occupy the full width specified in your margin settings. This directive positions the imaginary rectangle occupied by the text in the center of your margin settings, regardless of the text justification directives. For example, the JL directive by itself might produce the following effect (the | character indicates margin boundaries; the _ is for spacing):

| The quick brown fox ____________ | | jumped over the lazy dog. ______ |

but the JL directive together with JBC will preserve the text justification but center the block of text between the margins:

| ___ The quick brown fox ____ ___ | | ___ jumped over the lazy dog.___ |

AnimEigo video products have their subtitles displayed this way.

JBF

Justify block full (default). Text will be positioned according to whatever text justification directives are in effect, using the full width specified by the current margin settings.

JBL

Justify block left. Position the text block at the left margin.

JBR

Justify block right. Position the text block so that the right edge is at the right margin.

[Wordwrapping]

W0

Disable automatic wordwrapping. This may result in your text not fitting within the position constraints defined with H & V. There is really NO reason at all why you would want to turn off wordwrapping; you can wrap words manually with the \n code whether wordwrapping is on or off. This directive is here just for the sake of completeness.

W1

Automatic "smart" wordwrapping (default). Even if your text contains newline codes, the separate substrings will be word- wrapped if necessary. This wordwrap mode uses a "smart" algorithm that attempts to minimize the area of the screen occupied by the title. In this mode, you will never see a line wrapped as shown (the | characters indicate margin boundaries; the _ is for spacing):

| The quick brown fox jumped over the lazy | | _________________ dog. _________________ |

Instead, the W1 alghorithm will attempt to minimize the text area without using any extra lines, resulting in:

| _________ The quick brown fox __________ | | ______ jumped over the lazy dog. _______ |

This is easier for the viewer to read. Same margins, same number of lines, but the lines are more equal in length.

W2

Automatic "stupid" (generally known as "greedy") wordwrapping. If you are disconcerted by words not completely filling the horizontal margin space, and you don't mind having a single word hanging by itself on the last line (as in the first W1 example above), then use this directive. This is the standard text-editor wordwrap algorithm, which makes no attempt at aesthetics. Why anybody would want to use this is beyond me, but here it is. \n codes behave the same as with W1.

Fonts

[Font rendering]

Fn

Use font n, where n is a number from 0 to 9 (JACOsub loads four fonts, which you can specify in the Config menu. The usual default font is 0, which is what you should use as your "primary" font.

FQ (Amiga)

Quick&Dirty text. Text color 3 is always quick. Other colors must normally be rendered one character at a time to avoid interference between the shadow and face color, but only when the font is designed with overlapping characters. This interference happens because of a fault in the way the Amiga renders text. The FQ directive forces all text on a line to be rendered in quick mode as if it were color 3.

You should never need to use the FQ directive. The program is smart enough to determine when a font can be quick&dirty. For example, JACOsub's 32- and 36-pixel fonts will default to clean mode because they have overlapping characters, but the 29-pixel font will default to Quick&Dirty because its characters do not overlap.

FC (Amiga)

Clean rendering. Only color 3 will be rendered fast, other colors will be rendered so that the face color is not disturbed. You can use this directive to negate, on a single line, a global FQ directive set using the #D command. Normally this directive will never be needed.

The demo script demo.jss tricks JACOsub into generating "slow" clean text in the foreground display so you can see how it is. If you are curious to see how the Amiga messes up color 1 text if it's displayed the quick way, run the demo after inserting the global command #DFQ at the top of the file demo.jss before you play the demo.

FD (Amiga)

Default text rendering. Rendering will be "quick" or "clean" depending on how your font was set up in your configuration. This directive is useful for overriding a #DFC or #DFQ command.

FBn

Blitter activity. This overrides the "Use Blitter" program configuration setting. If n=1, the blitter will be used to copy text between background video buffers for titles that extend over several time events. If n=0, then time-overlapping text will be generated afresh on each video buffer. Normally, the blitter should always be enabled. However, blitting between buffers will also copy any imagery behind the title (like a graphic or shaded background), which might not share the same time range as the title. If this happens, then disable the use of the blitter for that title with the FB0 directive.

FOn[:a]

Generate an outline around the font, n pixels wide. Color 2 (JACOsub's outline color) is used to generate the outline. This directive is useful for transforming a plain mono-color Amiga font into a nice titling font, especially when combined with the FS (font shadow) directive. Recommended value for n is 2, which produces a nice flicker-free outline. n must be less than 127. The maximum practical value is 3 or 4. The default value is 0.

The optional :a suffix indicates a color to use for anti- aliasing. This defaults to the anti-alias setting in the Playing / video configuration, typically 2 (no antialiasing).

WARNING: Generating outlines can slow the program down considerably! It is recommended that you use this directive only with QUICK&DIRTY font rendering, preferably with mono-color fonts. An antialias color other than 2 will slow it down somewhat further.

FSdn

Generate a font shadow, taking into account any existing font outline, in direction d, and n pixels deep. Color 2 (JACOsub's shadow color) is used to generate the shadow. The direction d is specified as a compass direction: N, S, E, W, NW, NE, SW, SE. Good values to use for the shadow depth n are 2 - 5. The warning about font outlines above applies here also.

Example: FSSE3 produces a shadow similar to the JACOsub 32-pixel font, with the shadow extending down and to the right.

[Font style] (may also be set with \ codes in the title text):

SN

Normal style (typical default).

SI

Italic.

SB

Bold (using the JACOsub font, this doesn't look good with colors other than color 3).

SU

Underline (ugly! Not recommended).

[Font color]

CFn

Use color register n for the face color of the font. JACOsub assumes that all color fonts use bitplane 0 (i.e. color 1) for the face color, and bitplane 1 (i.e. color 2) for the shadow/ outline. THIS IS IMPORTANT! JACOsub will generate text differently depending on the color selected (see FF above). The foreground color may also be set using the \Cn code inside the text.

CBn

Use color register n for the background color. The display will be cleared to this color prior to building the text. If two lines share the same display, and they have different background colors specified, the screen will be cleared using the latest NON-ZERO background color that occurs for that display. In other words, non-zero colors override the default zero (transparent) background color.

CPn

Use color palette n for this display. Default value of n is 0, which is the primary color palette normally used by JACOsub. The values of n may range from 0 to 9, for a total of 10 color palettes. All 10 palettes are initially set to a master palette which can be modified in the Playing / video Config menu, and they can be modified with the #Palette script command.

Because the palette is loaded immediately following a video buffer switch, the new imagery on the display will appear with the old palette momentarily. If this is too noticeable, then you should precede your alternate-palette lines with a "dummy" short-duration blank screen (containing a hard space) using your alternate palette, as in this example:

0:00:12.20 0:00:12.22 cp2 ~{palette 2 on blank screen, .02 sec} 0:00:12.22 0:00:14.50 cp2 This will appear with the new palette.

CS[L]n[:s[:c]]

This causes text to appear inside a shaded rectangle. The rectangle will be large enough to contain the text with a margin of n pixels on all sides. The shading is user-defined (see the Playing / video Config menu) if s=0, or solid if s=1. Color c will be used for the rectangle. The style (s) and color (c) paramters are optional; not setting them uses the defaults, normally s=0, c=2 (user-defined, black).

Setting n=0 disables the shading. We suggest using n=8 or more. Without the [L] parameter described below, only ONE shaded background rectangle will appear on the screen; that is, JACOsub will attempt to create a SINGLE box which contains ALL text that uses the CS directive and shares the same display. If two shading directives for the same time range have conflicting parameters, one of the directives will be used, but predicting WHICH one is impossible. The normal default setting is CS0:0:2, which can be changed using the #D command.

The optional [L] parameter causes each text segment (which might be split by wordwrapping) to be shaded in its own rectangle. This looks ugly for a block of wordwrapped text, but it is useful for shading separate single lines that overlap in time.

Notes: Setting VB0 will mean that bottom-positioned text is as low as it will go, therefore shading cannot appear below it. You should set the VB directive so that there is room for the shading rectangle to extend below the text. Also, VB text will be repositioned slightly higher when the running clock is displayed during play, but shade boxes will NOT be repositioned.

Genlock fader control (Amiga only)

GBn[Tm] (Amiga): Move the background slider control to n% saturation over a time period of m/60 seconds of time. n may range from 0 to 100. If time specifier is omitted, it defaults to 0 (i.e. instant). Zero saturation is a normal transparent background, allowing the video signal to show through all areas corresponding to color 0 on the computer's display.
Example: GB63T120 slides the background fader to 63% saturation in 2 seconds (120/60 seconds).
GGn[Tm] (Amiga): Move the graphics slider control to n% saturation over a time period of m/60 seconds of time. 100% saturation is the normal operating mode (full graphics), whereas 0% results in only the video signal with no overlaid computer graphics.
Do not use GG or GB in default directives, or the genlock will be having control signals sent to it at every time event.

IFF graphic files (obsolete, see R directives) (Amiga only)

IL: Same as RLB. Retained for compatibility with previous versions.
IS: Same as RLG. Retained for compatibility with previous versions.

Special effects

Basic information and warnings:

Only one effect can exist per time event. If two titles share the same start time, but have different effects, only one effect will be executed for both titles.
All these effects must be given sufficient time to complete. Any time events that occur while the effect is in progress will be postponed until the effect is finished executing.
With the exception of effects EN or E0, and ES, an effect directive will be ignored if the bitmaps for the current view and next view are incompatible (having different dimensions or depth). This is not a problem for transitions between two normal video buffers; but the effect will be ignored if you try to transition to a graphic screen having different dimensions or display mode from the image currently displayed.
In the descriptions below, the "d" parameter controls the direction of the effect, if applicable.
The optional "[s]" parameter controls the speed of the effect, which may range from 1 to 64 (default is 8 if omitted). The speed represents raster lines per vertical CRT blank. If s=0 or s=?, the speed will be randomly chosen.
If you notice "roughness" in the way these effects operate, try reducing either the effect speed or the number of colors you use for script playback.

EBd[s]

Blinds. New view replaces old view as if Venetian blinds were opened. Direction d may be V or H to specify vertical or horizontal blinds.

ED[s]

Dissolve. New view replaces current view by random memory replacement. There are only three speeds: slow (s=0-9), medium (s=10-19), and faster (s>20). This is probably not the best algorithm for a dissolve -- if anybody can write a better one, please send it to the author. It needs to be cleaner and faster. As it is, the only really useful speed is the maximum (s>20). The actual speed will depend on your video buffer size (width, height, number of colors).

EEVd[s]

Reveal next view as if Eyelids open (d=O) or close (d=C) vertically over the current view. This is actually two simultaneous vertical wipes in opposite directions on the top and bottom halves of the display.

EEHd[s]

This is a horizontal-wipe Eyelid effect. It vaguely resembles the opening or closing of curtains.

EId[s]

Reveal next view as an Iris opening (d=O) or closing (d=C) over the current view.

EN

Normal transition (default). New view replaces old. Also E0.

EPn[:s]

Palette fade. Transform the current title palette to palette n in [:s] video fields. This effect will be ignored if applied to a graphic file. Speed may range from 0 to 255, instead of 1 to 64, and the default speed is 32.

EP+a[:b[:p]]

EP-a[:b[:p]]

Cycle forward (+) or backward (-) colors a through b (default b is the maximum color index) with a period of p video fields per cycle step (default 2). This effect terminates at the next time event. [:p] may be as high as 255.

ERd[s] (Amiga)

Smoothly Roll the current view off the display while rolling the next view in. The direction d may be U, D, L, R (up, down, left, right). Caveats:

This effect consumes much memory: the equivalent of two additional video buffers. You may have to reduce your usual number of buffers or colors to make this effect work.
Horizontal rolls (left and right) are not possible under AmigaDOS 1.3. They will be converted to up and down, respectively.

ESd[s] (Amiga)

Scroll new view up into the display if d=U, or reveal new view by scrolling current view down if d=D. This directive will also work if the bitmaps are incompatible, i.e., if either view is an graphic view created by the RLG directive. This is not a "smooth" scroll; you may not find it acceptable.

EWd[s]

Wipe next view over current view in the given direction d (U=up, D=down, L=left, R=right).

E?[s]

Random transition chosen from those above, with random speed if [s] is also a question mark (?), or zero. Ignored for incompatible bitmaps when applicable. The Random effect does not include the Palette effects.

Argument directives (using the title string as parameter arguments)

DO NOT USE THE R DIRECTIVES IN A #D DIRECTIVE DEFINITION.

RLB <ILBM file name> [<x offset %> <y offset %>] (Amiga)

Load Bitmap. Load an IFF graphic file (typically a brush file) into a video buffer for the time interval specified by the start and stop time. When this directive appears, JACOsub assumes that the remainder of the line is information about the file, NOT title text. The file name must follow the directive string. The position to display the image, specified as percent of screen width and height from the center, can be specified in the next two fields. These position coordinates default to 0 0 if they are omitted, which results in the picture being centered on the screen. The picture may be positioned to extend beyond the display edge.

Any IFF graphic picture or brush may be specified. As many as 40 images may be loaded onto a single screen. This enables you to create several small brushes and display them all at once, in different areas of the screen.

CAVEATS (READ CAREFULLY!):

You need at least AmigaDOS 2.0 to use this directive. Under 1.3 and below, this directive is ignored unless you have a 1.3-compatible version of iffparse.library in your libs: directory.
If a file is too big to fit in memory, the file will simply not load, and the program will beep to alert you.
If the graphic file contains more bitplanes than the JACOsub video buffers, the EXTRA BITPLANES WILL BE IGNORED. You may change the number of JACOsub's bitplanes in the Playing / video Config menu. If you have JACOsub set for a 4-color (2-bitplane) screen, and you try to load in a 16-color (4-bitplane) picture, you will lose 2 biplanes of information, and the picture will look strange when it appears.
All pictures are treated as brushes. Therefore, your picture, once loaded, will use JACOsub's color palette. THE PICTURE'S OWN COLOR PALETTE WILL BE IGNORED. Create your graphics using the SAME palette you use with JACOsub or the picture will look strange when it appears. If you want to load a picture with its own colors, use the RLG directive (but then you won't be able to display text on top of it).
JACOsub attempts to load graphic files as they are needed. This can cause a slight video switch delay if a time event occurs while a file is loading, even though the graphic loading routines do check the clock frequently. Keep your images on a fast hard disk, or better yet, in RAM:. If you do not have sufficient memory, then do not use this directive!

RLG <ILBM file name>

Load Graphic. Load an IFF (Amiga) or PCX (MSDOS) graphic file into memory to to be displayed, in all its glory, at the appropriate time. On the Amiga, the picture will temporarily replace one video buffer. Under MSDOS, the file is loaded into one of the buffers. As with RLB, JACOsub assumes that the text following the RLG directive contains the file name to load. JACOsub will attempt to center the picture on your display.

The RLB caveats 1, 2, and 5 above apply here also, and the RLG directive has some additional considerations:

You cannot display text on top of a picture loaded with the RLG directive. Use the RLB directive for this.
The time ranges associated with a graphic screen should NOT overlap any other time ranges. If they do, the start time for the graphic has priority over any unrealized end times.
(MSDOS only) This directive loads a PCX file into one of the video buffers. The picture MUST be the same resolution and color depth as your display mode. That's 640x400x256 for HIRES, or 800x600x16 for SUPERHIRES.
(Amiga only) The RLG directive can tax your memory even more severely than RLB, especially if you load a pictures like hi-res HAM images to substitute every video buffer.
(Amiga only) We observe difficulty loading Extra-Halfbrite pictures. Try it. HAM and AGA images seem to work OK.

RDB <LeftEdge> <TopEdge> <RightEdge> <BottomEdge>

Draw Box. Draw a solid rectangle in the current text color with diagonal corners at the coordinates specified. Coordinate units are percentages of the display width and height. This is useful for making video letterbox margins really black. To make the rectangle appear behind text, be sure it occurs in the script physically before the text, with a start time less than or equal to the text start time.

RX <ARexx script name> (Amiga)

Execute the ARexx script name that follows the RX directive. You should not specify other directives on the same line. Only one RX directive may be specified per time event -- that is, if you have several lines all sharing the same start time, no more than one of them may contain an RX directive. If more than one RX directive is specified for a given start time, the one that occurs latest in the script will be used. The end time for the line is ignored, but should be larger than the start time to avoid a compiler warning. Try to make the end time equal to the next nearest start time to avoid creating unnecessary video frames.

Default directives

Because all of the above directives are optional, there is one other set of directives that may be used when you do not wish to specify any:

D or D0

Default. To be used if no other directives are used. You don't even need this directive at all, if your text begins with a non-alphabetic character (such as a {comment}, number, etc.).

Specifying D (or nothing) will use the program's default settings. The default directive for JACOsub is normally

HL1HR99VH100VT16VB16JCJBFW1E0F0FDFB1FO0:2FSSE0SNCF3CB0CP0CS0:0:2

which you can change in the file JACOsub.Config, or with a #D command at the top of your script. Confused? Here they are spaced out:

HL1 HR99 VH100 VT16 VB16 JC JBF W1 E0 F0 FD FB1 FO0:2 FSSE0 SN CF3 CB0 CP0 CS0:0:2

The R directives and the Genlock directives should NEVER be specified globally, nor in JACOsub.cfg.

Dn

The directives D1 - D30 may be defined with the commands #D1 - #D30. You can use these "default" directives as shorthand for more complex directives that you may need in many places. If you put two D directives in the same directive string, the latest one will be used, and any previous directives ignored.

[name]

A name enclosed in square brackets may be substituted for any of the D directives. You must have previously defined this name when you defined the D directive.

Other directives may be appended to a D directive to modify the behavior of that D directive. For example, if you defined a directive to use font 0 and color 1, and decided to name it "credits" then you would say:

#D2 F0CF1 credits

Then, if you wanted to use the D2 (or "credits") directive with font 3 instead of font 0, you could modify the directive either of the following two ways:

0:00:12.01 0:00:19.20 D2F3 Leia performed Akira's voice. 0:00:12.01 0:00:19.20 [Credits]F3 Leia performed Akira's voice.

You can spell the directive name using uppercase or lowercase characters.

If a directive string contains conflicting information, the information occurring last will be used. For example, VTD will cause VT to be ignored in favor of the default. In the directive CF10JLCF3, CF10 will be ignored in favor of CF3. Naturally, any directive beginning with D is unaffected by the D. In the long default directive above, you can see VT16VB16. This serves to set the top-of-screen offset to 16 for later, and then sets the default vertical positioning at 16 pixels from the bottom of the viewport.

Time track

Tx: Designate this line as belonging to track x, where x is any of the characters 0-9, A-F (case insensitive), or punctuation. This directive is ignored when compiling and playing scripts. All titles default to T0 if no track is specified.

The purpose of tracks is to let you assign unique designations to specific title sequences interwoven with others in your script so that you can time them separately.

For example, suppose you need to subtitle two people talking simultaneously with music lyrics in the background. This requires three independent timing sequences. There are two ways to do this:

Separate blocks of titles. Without using the T directive, you must arrange each sequence as a separate block of titles (remember, JACOsub doesn't care about order of the titles in your script file -- it will sort everything out according to start and stop times).
One block of titles containing designated time tracks. You can weave all the titles together as one long sequence, and designate separate tracks with the T directive so that the timing procedure can figure out which titles must be timed, and which must be skipped.

TRACKS WILL BE IGNORED IN ALL DEFAULT OR USER-DEFINED DIRECTIVES. Furthermore, as far as JACOsub is concerned, tracks are not treated internally as true directives at all. Their only use is to flag lines for the program's timing functions.

5. SAMPLE LINES

These 4 lines all have the same effect. Note that any spaces after the directive and the first space after comments are ignored.

0:00:10.11 0:00:12.00 D {fudo-ikiteru} It's alive! 0:00:10.11 0:00:12.00 D {fudo-ikiteru}It's alive! 0:00:10.11 0:00:12.00 D It's alive!{line doesn't start with a comment} 0:00:10.11 0:00:12.00 {fudo-ikiteru} It's alive!{starts with a comment} 0:00:10.11 0:00:12.00 [default] {fudo-ikiteru} It's alive!\ {this assumes the D directive was named to "default"}

If you want leading/trailing spaces, all of these lines will do the same thing (put two spaces in front of and after the text):

0:00:10.11 0:00:12.00 D ~~{fudo-ikiteru} It's alive! ~ 0:00:10.11 0:00:12.00 D {fudo-ikiteru}~~It's alive!~~ 0:00:10.11 0:00:12.00 D {fudo-ikiteru} ~~It's alive!~~ 0:00:10.11 0:00:12.00 D ~ It's alive!~~ 0:00:10.11 0:00:12.00 ~~{fudo-ikiteru} It's alive! ~ 0:00:10.11 0:00:12.00 {fudo-ikiteru}~ It's alive!~~ 0:00:10.11 0:00:12.00 {fudo-ikiteru} ~~It's alive!~~ 0:00:10.11 0:00:12.00 {fudo-ikiteru} It's alive!~~

THE FOLLOWING LINE IS BAD. It needs either a directive after the timing numbers, or a comment to indicate that subtitle text follows the timing numbers. Any alphabet character (A-Z, a-z) following the timing number MUST be part of a directive.

0:00:10.11 0:00:12.00 It's alive!

For the next line, use color 1 for the font face color, start the subtitle at the top of the screen and leave the other defaults alone, and cause one word to be displayed in italics:

0:02:23.23 0:02:25.01 cf1vt {thug1-nani} Whaddaya \Imean\N, ``please?''

Note: Normal quotation marks ("like this") may be used, but using a double grave and a double apostrophe, as in the line above, looks more professional on the screen. Just make sure that the grave looks like an upside-down apostrophe in your font, and that both characters occupy a narrow space. The JACOsub fonts are designed this way.

Additional note (this is one of the big features of JACOsub): Timings may overlap! The software will handle overlapping text displays properly, but you must be sure to position your subtitles so that these separate text events do not physically overlap on the screen. You can arrange timed lines in any order you want, separate overlapped events into groups, or whatever. The program will handle it.

6. CREDITS

The original JACOsub format was dreamed up by Alex Matulich and Daric Koslowski, before any code was ever written for JACOsub. Yes, this was the second step! (The first was to create the fonts.) Beta testers and users have been very helpful in expanding and improving the specification into what it is today. User feedback has played a large role in the development of the software and the script format. The entire JACOsub project has been largely user-driven.