MACJSUB DOCUMENTATION Operational notes: ================== The text editor and application shell come from WASTE 1.3. Note that I have found a bug in this text editor. If you select all and try to change the font, it may hang. It may also matter than I have the Japanese Language Kit installed. NOTE: Because of this, you should have the file "WASTELib" in the same directory as the application. It is the guts of the text editor. The file and edit menus are pretty standard. The font/size/style/color menus only affect the text in the editor window and have nothing to do with the subtitling output. But it will be necessary to select a Japanese font when JLK support is added so that you can read it. (Such files will be saved as Shift-JIS.) The Features menu is part of the WASTE demo application shell and I will eventually condense it into a preferences dialog. I hate drag and drop and don't much like "intelligent" cut and paste, so I will be sure to make it remember when you disable either of these options. Double-clicking on the output window will set its coordinates to 0,0. This is currently designed for a 640x480 output window and a white genlock color. This is what MacSubtitler uses, and it's the only other thing out there so far. I'm using a 7100AV and the DesktopTV application. I will probably write a replacement for DesktopTV which does the backdrop window and none of the other options. (But I will leave in the digitizer preferences, because that's where you have to be able to select the input type to VCR for enhanced time base correction.) No other overlay methods are yet supported, even if they are in the menu. The first text window open will become the "primary" script window, unless you select the Set Script Window item from the Special menu. Scripts are not automatically recompiled when you change the text. You can run free-run the clock with command-1 and command-2. Useful for genlocking over a tape as a time reference. Sorry, but you can't change the clock font yet. If the script is not compiled, command-R will also compile it. This is not recommended because the script will not start at a predictable time. If you stop the running script with command-., you can hit command-G to continue from the current time. But you can't yet start at an arbitrary time. When a script is running, hit the left arrow to advance the clock (if titles are coming on too late) or the right arrow to retard the clock (if titles are coming on too soon). Time is adjusted by 1/10 sec unless you have the option key down, in which case it is adjusted by one #TIMERES increment. Note that titles always come on in their intended order. Using the arrow keys will neither cause titles to display twice, nor will it cause them to never appear. Command-M hides/shows the menu bar. Beware of crashing with the menu bar hidden. If this happens, you may not be able to hide it again until after you restart. I didn't go out of my way to handle out-of-memory conditions gracefully. But I did give it a large enough partition to work in "normal" cases. You can give it more if you feel like it. Unlike JACOsub, if times get shifted to negative numbers, they shouldn't cause problems. This can be useful when you want to tweak something in the middle of a script. Just add a negative shift to slightly before the title you want to see, re-compile, and run. Italics are a pain in the butt because I don't have a good way yet to measure their overhang. Too much overhang can result in "pixel turds". Off-screen buffers reduce the chance of this, but it can still happen with some fonts. Just remember when ending a line in italics to watch for a heavy slope. STR# 256 contains the default fonts. These come in pairs, with the font name and the font size. STR# 257 contains the default directive. The first string is used for the "factory" default, and second string is used for personal preference changes, such as if you want to use "JLJBC" as a default. When a script is running, WaitNextEvent is called with a zero sleep time to ensure hogging the CPU. Those of you converting from MacSubtitler may find you need to use a ramp of about -9 seconds per hour. This is because MacSubtitler uses TickCount for timing, and it runs at 60.15 ticks per second, not 60.00. This is the vertical sync rate of the original Macintosh models. In MacSubtitler where it mentions this, it is worth noting that the example is 4.7 secs for 30 minutes. Of course it had problems with scripts timed on Amigas... because JACOsub's clock works better! MacJSub's clock is phase-locked to your real-time clock This is a bit TOO accurate if you are using frame numbers from a CAV laserdisc, as interlaced NTSC runs at 29.97 frames per second, and the JACOsub documentation implies that its clock is based on an input from the genlock. But according to my math, the error will be 1.8 *frames* for a full 30-minute CAV side, which would need only a -0.06 second ramp. So don't worry too much. Important differences from JACOsub script format: ================================================= A lot of Amiga-specific features aren't supported, including scrolling, graphics, etc. Section 1 --------- I'm not yet supporting tabs as whitespace. The 511 character limit is specific to the text editor in the Amiga version of JACOsub. But I may add a horizontal pixel limit in the future, so I can turn off word wrap in the text editor windows. Section 2 --------- The following compiler commands are not yet supported: #Q #I The following compiler commands will probably never be supported: #H #R and #S don't care whether they occur before a #T command or not. If they do, they will just use 30 units/sec. Everything gets converted to milliseconds anyhow. The way three or more #S commands work is not well defined in the spec. The way I implemented it is to make the first one global, to be applied along with #R. Any subsequent #S commands are offset ONLY by the global #S. So a third #S is not affected by the second #S. Also, it doesn't matter if the result causes times to go negative. The "before zero" subtitle lines just get dropped. This is useful for starting in the middle of a script since I have no "start at time" command yet. Font names containing blanks can be put in double-quotes. JACOsub font names probably won't work unless you just happen to have fonts by those names installed. Font stretching is not supported. When supported, #I will be able to take a negative offset. Just because. Section 3 --------- A \ at the end of a line for concatenation is NOT yet supported. \D and \T are not yet supported. \Fn is not yet supported. Trailing spaces may not be properly ignored. Section 4 --------- The following directives are not yet supported but eventually may be: VHn JF[:p] FOn[:a] FSdn CS[L]n[:s[:c]] The following directives will probably never be supported: VS[n] FQ FC FD FBn GBn[Tm] GGn[Tm] IL IS RLB RLG RDB RX and all effects (Ex) The VU directive does not affect previous VB or VM directives, but it will work correctly with VT. This is one of those things that is easy to do with the Amiga's graphics chips, but much trickier when you may have already started drawing the VB or VM line at its original coordinates. But I may be able to make these work. HL and HR are limited to a range of 0 to 100. I really don't know why they bothered to allow larger ranges in the JACOsub spec. The vertical coordinates of Vx directives are only 0-400 in the standard video mode of Amiga JACOsub. They are offset by 50 pixels to center them vertically (more or less) within MacJSub's 480 pixel high window. Palette animation via CPn will not be supported. Future stuff ============ * verify that shadow and background colors do indeed come from the palettes * Add \Fn for multiple fonts in one line (ascent and descent need to be accumulated) * Start at arbitrary clock time * Arrow key time ramping with up and down arrows * fractional widths * Better font buffering/text drawing to reduce the "paint-on" effect -- I already have ideas for better buffering/drawing methods, which should speed up shadow drawing considerably, by using one extra B&W bitmap per buffer and one more scratch B&W bitmap. Shadow drawing will be on the order of x+y rather than x*y, and the text will only be drawn once for a further speed increase. * script manager support, or at least support for Shift-JIS text -- note that I really only care about supporting Japanese. Right-to-left scripts are of no interest to me, and if it doesn't take much extra work to support Korean, I may eventually do it. Alas, but I don't think I can properly reconcile JACOsub's '~' character as a non- breaking space for either TextEdit's or WASTE's text wrapping. Smart-wrapping would not be easy, either. But if I could leverage either text editor package, WorldScript support would be inherent. * full justify (For full justify, the number of spaces in the line should be recorded when line breaks are calculated. Or at least the amount of space to advance for each one.) * I will add support for more overlay methods as I have a need for them. * The clock window will have more stuff it can display by double-clicking on it or using the (not drawn) grow box. Stuff like current ramp and shift values. * Search and find. The SimpleText 1.4 source code should have something usable. * multi-bit fonts (without any available editors, an Amiga -> Mac converter is needed) I'm not really sure this is worth the trouble if a good text buffering method is used. * An option to set the frame rate for "@" times (because interlaced NTSC is 29.97 fps) In milliseconds this comes out to 33.3667ms per frame, which isn't accurate enough when rounded off, so this should probably be stored as a float and multiplied. Without this, you would need about a 1 second per half hour ramp. * Progress bar for long compiles (mostly irrelevant now that it's so fast) * Collision detect (this would slow down compiling) I'm writing this in three phases. Phase 1 is a solid core with an accurate clock, a good text editor that can handle WorldScript and files larger than 32K, and with most of the JACOsub spec implemented. Phase 1 is esentially complete. Phase 2 will add awareness of the editor windows to select text for errors, and to modify selected text (such as time shifting, etc.) This is also when I should clean up the menus, and move the "Features" menu into a preferences dialog. #I could be implemented by opening the included file as a window, or the file reference could just be stored somewhere in case an error needs to be displayed. Detecting script changes will also be added in this phase. Phase 3 will add timing features. Until then, using MacSubtitler and a 9 sec/hr ramp will have to do. Which means that applying ramps and shifts should maybe be one of the first phase 2 features to be implemented. Or maybe I can start with some very basic timing features in phase 2. CHANGES ======= 1.0b2 Adjustments have been made to match JACOsub's 400-line coordinate space. 50 pixels are added to all vertical positions. While this doesn't (normally) let you use the vertical overscan areas, it provides a closer representation of the coordinates selected by the original subtitler. The VP directive is supposed to position the *baseline* of the first line of the text, and I was positioning the top of the entire text block. Oops. This would have caused VP text to appear 20 lines below where it should have, but without the 50 pixel adjustment above, this caused them to appear 30 pixels above where they should have.