JACOsub: video titling software for professionals version 2.4 Timed Script Editor and Player A Product from Unicorn Research Corporation This file contains information about running the JACOsub software. For a general overview (installation, features, etc.), please refer to the file Overview.doc. JScripts doc contains the complete script format specification, QuickRef.doc is a quick summary of JScripts.doc, FAQ is a list of frequently asked questions, ARexx doc contains information about ARexx communications, and Register.doc contains registration information. CONTENTS OF THIS DOCUMENT ========================= 1. Running the Program 2. The Editor Window 3. Pull-Down Menus 4. Notes About Playing Scripts 5. How to Time a Script In Real Time 6. Configuration File Format 1. RUNNING THE PROGRAM ======================= Workbench --------- Just click twice on the JACOsub icon to start the program. Skip to the "Menu" section below. Shell ----- The Shell command for running JACOsub is simply jacosub [-switches] [scriptname] Command arguments are optional. Scriptname is the name of the script to play. If you specify ONLY the root name of your script (that is, with no .extension), JACOsub will look for the following 5 files: scriptname.js (JACOsub script) scriptname.tts (TurboTitle script) scriptname.pjs (Phoenix Japanimation Society script) scriptname.tim (generic timed script [actually same as .pjs]) If more than one of these are found, the newest one will be read in. Additionally, a compiled script of the same name (with the extension .jsc) will also be loaded if it is newer than the script you specified. JACOsub optionally saves its compiled script so that it will load up quickly in the future (it can take a few minutes to compile a long script). The compiled script is typically over 3 times the size of the uncompiled version. Default behavior is for this automatic saving to be disabled, because you are likely to be fiddling with your script, which will require a recompile anyway. If you DO specify one of the above extensions in your script name, then JACOsub will attempt to load that specific script, plus the compiled if it exists and is newer. For Panimator (.pan), Subtitle (.sub), and ZeroG (.zeg) scripts, you must convert them to JACOsub format before loading them into JACOsub, using the JConvert utility. See Overview.doc for more information. Switches: -config lets you specify a configuration file. The file name must appear following a space after the -config switch. If this switch is omitted, JACOsub will look for the file JACOsub.cfg in the current directory. -register takes you through the registration procedure. You will be asked for your name and registration code. After entering these, the program will permanently modify itself to reflect your ownership. Some features will be unlocked, and the script play display will not have that little logo in the lower right corner. See the "Shareware Notice" and "Commercial License" sections near the end of this document for details on obtaining a registration code. This switch is the same as clicking twice on the "register" icon. -trace displays a trace of program execution during initializations. If JACOsub crashes when loading, try this switch, then write to the author and describe what was displayed. -any other switch causes a help message to be displayed. During script compilation, JACOsub will inform you of its progress as well as any errors that it finds in your script. Example ------- To see how it all works, run the demo script (called demo.js). There are three ways you can do this: 1) From JACOsub: After starting JACOsub either from the shell or from Workbench, press right-Amiga-O Open a script, and select demo.js from the file requester. 2) From a Shell: Just make sure that demo.js, idemo.js, and JACO.bbm are in your scripts directory, and type this command: run jacosub demo 3) From Workbench: Click ONCE on the demo.js icon. Then, while holding down the SHIFT key, click twice on the JACOsub icon. Once the script is loaded, press right-Amiga-P to play it. It will be compiled first if needed. 2. THE EDITOR WINDOW ===================== The first thing you see when you run JACOsub is the editor window. Besides the pull-down menus, there are several operations that can be done with the keyboard and the mouse: - The Shift-Up and Shift-Down arrow keys will page the screen up and down. - The Shift-Left and Shift-Right keys will skip the cursor over words. - Clicking the mouse on the display will reposition the text cursor. - Holding down the mouse button on the top line, bottom line, left column, or right column of the display will cause the display to scroll. - Double-clicking the mouse on a line starts a block definition. Double- clicking somewhere else expands the block to the new position. Double- clicking again starts over with a new block definition. - The function keys F1-F10 may be defined to insert often-used strings. Set these with the "FKey macro" selection in the "Config" menu. - Press right-Amiga-T to toggle the cursor between the first line and last line of your script. - Press right-Amiga-] to toggle the cursor between the beginning and end of the current line. - Press right-Amiga-/ to toggle between insert and overstrike modes. 3. PULL-DOWN MENUS =================== There are five pull-down menus available in JACOsub, each with several selections. Many selections have a keyboard shortcut; these shortcuts are displayed alongside the selections. File -- file operations ----------------------- New Remove current script from memory. Open Open a new script and load it into the editor. The file must be a legal script type; that is, the name must end in .js, .tts, .pjs, or .tim. Insert file Insert a file ahead of the current line. You can use this selection to load up any ASCII file that is not an actual script. Save Save the script using the current name. Save as Save the script under another name. Save block Save the current highlighted block to a file. Print block Print the current highlighted block to device prt:. View IFF file Preview pictures in the graphics directory. About Display some information about JACOsub & free RAM. Quit Exit the program. Edit -- editing operations -------------------------- Block start Mark the beginning of a block at the current line. Block end Mark the end of a block at the current line. Clear block Remove all block markings. Select all Mark all lines in the script as a block. Cut block Cut currently-marked block from the script, and save it in the clip buffer. Copy block Copy currently marked block into clip buffer. Insert block Insert clip contents into script ahead of the current line. Delete line Delete current line under the cursor. Undelete line Insert last deleted line ahead of current line. Jump to line Enter a line number to jump to. Beg/End of line Toggle cursor between beginning and end of line. Top/End of file Toggle cursor between beginning and end of script. Overstrike Toggle between insert and overstrike editing modes. Search -- searching and replacing --------------------------------- Find Search for a string. Replace Search and replace a string (singly or multiply). Go next find/rpl Go to next search or replace occurrence. Script -- playing and other script operations --------------------------------------------- Play script Play the script, compiling first if needed. Pressing ESC during compilation returns you to the editor. Prior to playing, you may adjust several settings: play mode (normal, running clock, or manual step), ramp & shift values, and begin time. Play block Play only the highlighted block. View line See what current line will look like during play. MouseMove line Position a title with the mouse (WYSIWYG). Other titles and graphics which are timed to appear on the screen at the same time as the selected title, will also be displayed for reference, if the selected line is inside a highlighted block. Text Directive Display a dialog box allowing you to set directives relating to text appearance. The editor's cursor must be positioned on a timed line or on a #DIRECTIVE command line. This is easier than remembering all those directives (see JScripts.doc or QuickRef.doc), but you'll still need some knowledge of their capabilities before playing with this menu selection. Compile script Compile the script (this is automatically done when you play a script, so you will rarely need this). You can abort long compilations by pressing ESC. Time overlap warn Warn during compile if the time range for any line overlaps the time range for the previous line. Save compiled Dump the compiled script data structures to a file. The file will have the extension .jsc on its name. Timing -- operations for manipulating time events ------------------------------------------------- IMPORTANT: There are some operations where you are asked to enter numbers. In all of JACOsub's numerical handling, numbers after a decimal point DO NOT represent fractions of a second. They represent whole time units. 12.4 and 12.004 mean the same thing: 12 seconds plus 4 time units. The number of time units per second is determined by your #TIMERES setting in your script. Default is 30/second if not specified. Suppose you are using 100 units/second and want to specify 0.4 seconds. You must specify 40 UNITS. That is .40, not .4 (.4 would be 4 units, i.e. 0.04 seconds). Time block Time the lines that have timing numbers, in a highlighted block, or in a selected track in the block. See the section "How to Time a Script" below for more details. Punch-In timing "Plays" a pre-timed block in the timing display, allowing you to toggle between playing and timing by pressing the R key. The block, or the selected track, must be timed and the start times must be sequentially ordered. Ramp block Ramp-adjust times in a block for drift. Shift block Shift all times in a block up or down. Time-divide block Equalize the differences between start times in a block, so that all titles have the same duration. Auto-endtime Intelligently adjust title durations in a block, depending on character length, default minimum duration, and next-title start time. Time format & resolution (submenu) H:MM:SS.FF Convert times in a block to H:MM:SS.FF format. @Frame counts Convert times in a block to @FFFFFFF format. New counts/sec Change time resolution & format over entire script. Resolve #R's & #S's Resolve times for all #R and #S commands, and remove the #R and #S commands from the script. Insert dummy times Insert dummy start and stop times in front of every untimed non-blank uncommented line in a block. View play ramp&shift Show the current script play ramp & shift setting. Equivalences Calculate time equivalences between normal H:MM:SS.FF format, @NNNNNNN format, 1/60 second counts, and 1/50 second counts, for various time resolutions. Changing any input affects all the others. Config -- configuring JACOsub ----------------------------- NOTE: Selecting "Save" in any Config requester will save the entire program configuration, not just the information in that requester. The software must be registered to save program configurations. General settings Set general configuration parameters (these settings are listed under "General Settings" in the Configuration File section below. Fonts and Function Keys have their own menu selections. FKey macros Set function key macro strings. Titling Fonts View or set currently-loaded fonts to be used for playing scripts. The fonts shown are usually those that were initially loaded, unless they were overridden by your script. Playing / video Set play behavior parameters (includes both the "Play Behavior" and "video" settings described in the Configuration File section below). Load config Load a new configuration. Save config Save the program configuration (software must be registered). 4. NOTES ABOUT PLAYING SCRIPTS =============================== Play modes ---------- There are three modes; normal real-time, real-time with a running clock display, and step play. normal: This is the normal play mode to use when making a final master. * The "Loop" button appearing next to the Normal play selection causes your script to loop forever, which is useful for displaying cyclic scripts such as convention schedules. At the end of each pass, there will be a short delay while video buffers are refilled before the script begins anew. * Selecting "Beep" causes each time event to be signaled by a short beep during play. This gives you an audio cue to indicate script timing accuracy. running clock: This mode puts a small screen in front of the video title display, showing a digital clock plus ramp and shift information. You can drag the clock up and down. JACOsub will raise all bottom-positioned text a little bit so that the clock won't cover up too much. If it is covering too much for your taste, you can temporarily raise this text by inserting a command like #D VB32 in your script (see "Compiler Commands" in the file JScripts.doc). The clock display may appear to run erratically at times. This happens when JACOsub is too busy generating images in background video buffers and cannot update the clock display as frequently. Do not worry; internal timing is not affected. The clock display is mainly for using with a blank script so you can record a clock on your video for manual (that is, highly accurate) timing. The "Beep" selection works in this play mode also, although the "Loop" selection works only in normal play mode. step play: This mode allows you to step manually through your script to see how each screen will appear during real- time play. This play mode builds its imagery on the visible display, so you can see how each screen gets generated. The spacebar steps forward 1 screen, and backspace steps backward up to 3, 4, or5 screens, depending on how many video buffers exist. * The "Pre-load buffer" button causes imagery to be pre-loaded one buffer ahead of the current view. This is useful for live "on-air" environments where manual control is desired. Normally, pre-loading is turned off for step play. With no pre-loading, the buffer's time event is displayed in the top left corner, and the view is drawn while you watch. On-the-fly time shift adjustments --------------------------------- You may adjust the absolute time shift during play by pressing the + key to increase the times (i.e. delay them) and - to decrease the times. The amount of shift is changed by the ramp&shift increment you set up prior to playing the script. After your script is finished playing, you may select the "View play ramp&shift" menu to view the settings. On-the-fly ramp drift adjustments --------------------------------- During play, you can make ramp time adjustments on the fly. Suppose you have the ramp&shift increment set to 0.10 sec. Pressing the down-arrow key will decrease the ramp time adjustment by 0.1 seconds, and pressing the up-arrow key will increase it by 0.1 seconds. THE CHANGE WILL OCCUR AT THE TIME-POINT WHERE YOU CHANGED IT. For example, if the script play is 20% complete (1/5 done) and you pressed the up-arrow key, time events would be increased by 0.1 seconds AT THAT TIME -- this would increase the ENDING ramp time by five times that amount (i.e. 0.5 seconds) because the play is only 1/5 complete at the time you made the change. The running clock display will show you the ENDING ramp time. After your script finishes playing, you may select "View play ramp&shift" to view the settings. Beware of adjusting ramp time near the beginning of the script! Doing this too early in the play will result in a drastically huge change at the end (for example, if the playing is 1/100 complete, a 0.1 sec change in ramp time will result in a 10-second change near the end!). Don't be disconcerted by the Ramp display on the running clock; as stated before, it shows the ENDING ramp adjustment. On-the-fly ramp adjusting is *wonderful* when you get used to it. Usually you will only have to make two or three adjustments during the entire script play, whereas straight time shift adjustments have to be done many times at regular intervals to keep the script in sync with the video. >> If you find that you need more than 10 seconds of ramp adjustment per 30 minutes of script, then your genlock is having an adverse affect on your system clock. GET THIS FIXED. Do not use JACOsub to "fix" the problem with a bigger ramp adjustment; you are only CURING THE SYMPTOM of a serious problem, not the cause! Besides, if a ramp adjustment gets too large, an internal math overflow can occur, resulting in a sudden time-jump. If you need large ramps, get some technical support from your genlock vendor. << 5. HOW TO TIME A SCRIPT IN REAL TIME ===================================== The slowest but most accurate method of timing is to do it manually: step-frame your video, observing either a frame counter or a running clock pre-recorded on the video, and manually entering each time event into the script. This is how AnimEigo times their scripts. Real-time timing is quicker but often results in more errors. Either way, timing a script accurately is a tedious chore. JACOsub attempts to make this process easy and flexible in real time without sacrificing accuracy. Many errors occur from trying to time an entire script all at once. These errors are caused by operator fatigue, distractions, and short attention span. Fixing these errors is often a painfully slow process. JACOsub allows you to time your script in small sections. This process gives you the ability to correct small mistakes easily, and helps you keep your mind alert. Other features to make timing easier include on-the-fly mistake correction, and automatic title lowering so that you need only be concerned with raising titles, and a "punch-in" timing mode that allows you to make real-time adjustments to a block that has already been timed. To time a section of your script, first highlight it as a block in the editor. Before timing, each title to be timed MUST have a start and stop time; "dummy" values will work. If some of the highlighted titles don't already have start and stop times, the program will tell you and give you the option of inserting them. Or, you can select "Insert dummy times" from the script menu, and JACOsub will analyze the highlighted block and insert start and stop times to all the lines that require them. Check to be sure that the correct lines have start and stop times, and then select "Time block" from the Timing menu. You will see a dialog box with these timing parameters: Start at: This is start time of the first line in the block. The default value is whatever the current start time is for that line. This parameter is useful for "stitching" your separately-timed sections together -- just make sure that the first line of your next section is the last line of the current section. Minimum: Minimum duration of each title in milliseconds. All titles will have a duration of at least this amount unless superceeded by a new title. 2 seconds is a good value. Plus: Additional duration to add to the minimum, in milliseconds per character of title length. Longer titles take longer to read. 33 ms/char is a good number to use; experiment until you find a satisfying personal preference. Gap ____ msec if < ____ % diff: Number of milliseconds of blank space to insert between successive titles when raised with a forced gap, if the title lengths differ by less than the % change. Normally, raising a title before the previous one is lowered causes the previous title's end time to be the same as the new title's start time. This saves video buffers during script play, and allows for clean transitions between titles. However, if two successive titles look similar (e.g. same number of lines of same length), the viewer may not notice the title has changed while watching the video. Forcing a gap (see below) causes a brief blank interval to flash onto the screen, providing a more noticeably break between titles. Output resolution: Number of units/second to use when modifying the times in the script. The default will be whatever is current in your script. Track: If you have used the T directive to designate any of the highlighted titles as separate timing tracks, this cycle gadget will appear, allowing you to select, for timing, one or all of the tracks present in the highlighted block. After selecting OK, the timing display will appear. The top half of the display contains mouse and key instructions. This top half is mostly transparent to video, so you can view your video through a genlock while timing your script. The bottom half contains three fields: Used titles list: The last three titles timed to completion. Currently raised title: The current title being timed. Waiting titles list: The next four titles waiting to be timed. Initially only the Waiting list contains anything. Timing will begin when you raise the first title. The operations available to you are: Raise next title (SPACEBAR or left mouse button): Raise the next title in the Waiting list. If another title is currently raised, it will be lowered and placed in the Used list when the next title is raised. Raise next title with a forced gap (TAB or double-click left mouse button): Same as above, with the difference that if a title is currently raised, its end time will be shortened slightly to create a gap between it and the next raised title, provided the two title lengths are sufficiently different as specified in the timing set-up dialog box. Lower current title (RETURN key or right mouse button): Lower the currently-raised title if one exists. You should never need to do this if you have properly set your auto-duration parameters. Back up (BACKSPACE): If a title is currently raised, it is put back into the Waiting list. If no title is currently raised, the last Used one is put back into the Waiting list. You cannot back up if performing punch-in timing. Skip next Waiting title (DEL key): The next Waiting title is put into the Used list. If a title is already raised, it will be placed into the Used list first, along with the next Waiting title. Skipped titles will not have their times modified in the script. Abort operation (ESC key): Abort the timing and return to the editor. Script times will not be modified. Only by finishing the whole section will any times be modified. Toggle instructions, Used / Waiting (I, U, W keys): Pressing I causes the instructions in the top half of the display to disappear. Press I again to make them reappear. Pressing U or W changes the size of the Used or Waiting titles lists, respectively. They will cycle between 1 and 5 lines in height. The size of these fields will be saved for the future if you save the program configuration. After timing the script block, you may move on to the next section. Simply make sure that the last title you timed in the previous block is the first title to be timed in the next block. The start time of the new block will default to the start time of the first line in the block. In this way, the blocks are "stitched" together. 6. CONFIGURATION FILE FORMAT ============================= You can skip this section. JACOsub's configuration file is transparent to you -- you can modify the configuration from any of the Config menu selections, and the program saves its configuration in a file called JACOsub.cfg whenever you select "Save Config" from the Config menu (provided the program has been shareware-registered). JACOsub will set its own defaults for parameters that are omitted in JACOsub.cfg (and also if the file doesn't exist). The settings in the file are documented here just for the sake of completeness. When running JACOsub from a Shell, you can specify which config file you want using the -config commandline switch, or you can run JACOsub from whichever directory that contains the desired config file. Each line in the JACOsub.cfg file may be: a blank line, a comment (must begin with a # character), or a setting. Settings have the following form: SETTING ... Here are the settings and their possible arguments. They may be either uppercase or lowercase. The default settings indicated are what you get if you omit a particular setting from your config file. Parameters inside brackets [] are optional; those inside bra-kets <> are mandatory. General Settings ---------------- AUTOENDTIME [changed in AutoEndtime or Time Script menu selection] When timing a script or performing the Automatic End Time adjustment feature, JACOsub needs to know what default time duration you want for your titles. is the minimum duration in milliseconds. Titles appear on the screen for at least this length of time (this duration is shortened during timing if you raise another title before the current title has expired). is the additional amount of time to display the title, expressed in milliseconds per character. The character count of the title does not include directives, embedded comments, or embedded escape codes - only the title text itself. is the amount of blank space to force between titles when a new title is raised before the calculated end for the previous title. The gap will appear if the percentage length difference between the two titles is less than , otherwise the previous title will end when the new title begins. Setting to zero disables the forced gap. Default: AUTOENDTIME 2000 33 50 20% DIRECTIVE [changed in the General Settings menu selection] Sets the initial global D directive for all scripts. Don't be scared by the huge default string shown below; yours won't ever look like this. See the "Directive" section in the format specification documentation JScripts.doc for complete understanding. Anything you set here represents a *change* to the default string below, not a replacement. Default: DIRECTIVE HL1HR99VH100VT16VB16JCJBFFDF0FO0FSSE0SNCF3CB0CP0CS0:0:2W1 DURATIONWARN [changed in the General Settings menu selection] If you inadvertently set a title's start and stop times so that its duration is too long, you might want JACOsub to warn you about it when your script is compiled. This problem sometimes occurs when compiling TurboTitle scripts, where some "null" lines can have a start time of 0 and a stop time of 9 hours! This setting lets you set the minimum title duration that will trigger a warning during script compilation. Default: DURATIONWARN 120 EDITORWINDOW [changed with the editor window resizing gadget] This determines the initial position and size height of the editor window. Minimum window size is 420x150. To change this setting while using JACOsub, simply use the mouse to change the size of the editor window and save the program configuration. Default: EDITORWINDOW 0 2 640 198 FKEY [changed in the Fkey macro menu selection] You may set any of the 10 function keys to send a string (up to 80 characters) to the editor. This is useful to keep from typing commonly used strings over and over again. should range from 1 to 10, and you should not have a comment behind the macro string or it will be included as part of the string. Default: FKEY 10 9:00:00.00 9:00:00.0 D (This is useful for inserting dummy times in front of lines) Function keys 1 - 9 are not set. FONT [CLEAN or QUICK&DIRTY] [Y/X] [changed in the Title Fonts menu selection or changed by your script] Sets font to which is pixels high. must range from 0 to 9. The font should be a proportional-spaced color font, although you can use any font. You will normally NEVER need the last argument. The CLEAN argument (default for color fonts with overlapping characters if omitted) tells JACOsub to display this font "cleanly," that is, to avoid an artifact of the Amiga's text rendering operation that results in color interference problems when rendering fonts with overlapped characters (such as the JACOsub 36 and 32 fonts). With CLEAN, only color 3 text will be rendered quickly; other colors will be rendered one character at a time instead of a line at a time. QUICK&DIRTY forces the font to render quickly, with the resultant color interference problems. QUICK&DIRTY is the default for mono-color fonts and color fonts without overlapping characters. The Y/X parameter is the font's initial aspect ratio (AmigaDOS 2.0+), and defaults to 100/100. Once an aspect ratio is set for a certain font and size, it cannot be changed later. Defaults: FONT 0 JACOsub.font 36 (primary font) FONT 1 JACOsub.font 32 (secondary font) FONT 2 JACOsub.font 32 FONT 3 JACOsub.font 32 FONT 4 JACOsub.font 32 (Note: fonts 4 through 9 are FONT 5 JACOsub.font 32 not available unless the software FONT 6 JACOsub.font 32 has been registered.) FONT 7 JACOsub.font 32 FONT 8 JACOsub.font 32 FONT 9 JACOsub.font 32 Important point about fonts: Color fonts should be designed so that bitplane 0 (color 1) contains the font face imagery, while bitplane 1 (color 2) contains the outline and dropshadow imagery. JACOsub assumes all color fonts are designed this way. This design is necessary for face color control and rendering efficiency. The TurboTitle font was not designed this way, so it will look all wrong unless you use a font editor to reassign the bitplanes. GENLOCK [changed in the General Settings menu selection] Specifies how to interpret genlock fader control commands in a script (see the "Directive" section in the format specification documentation JScripts.doc). NONE will cause such commands to be ignored. Otherwise JACOsub will attempt to control the type of genlock specified. Currently only the Digital Creations SuperGen is supported, using supergen.library version 2.0 or higher. GVP genlocks can cause crashes when a program tries to load an IFF file without using GVP's own proprietary file loader. Setting GENLOCK to GVP will cause JACOsub to look for a script called gvpfade.jsrx for genlock fading (see the file ARexx.doc for details), and it will also cause a compile warning to be issued if your script tries to load an IFF file. The script will still compile properly, however. TOASTER specifies the NewTek video toaster, which like the GVP must be controlled through ARexx, and requires a script called toasterfade.jsrx. Default: GENLOCK NONE GRAPHICPATH [changed in the General Settings menu selection] Tells JACOsub the directory where it should expect to find IFF graphics. Default: the "scripts" directory under the current directory. GRAPHICPATH scripts MAKEBACKUP [changed in the General Settings menu selection] If set to YES, JACOsub will copy your original script on your disk to the T: directory before saving an updated version. Under normal AmigaDOS configurations, the T: directory is on the ramdisk. Default: MAKEBACKUP NO SAVECOMPILED [changed in the General Settings menu selection] Tells JACOsub whether or not to save compiled versions of your scripts automatically. Compiled scripts load up quicker than raw ASCII scripts, but they consume more disk space. You are not likely to need this setting. Default: SAVECOMPILED NO SCRIPTPATH