Contents Copyright Preface 1 Installation 1.1 The Install Program 2 Introduction 3 The Interface 3.1 The Script Files 3.1.1 RTLoad.script 3.1.2 RTQuit.script 3.1.3 RTPrefs 3.1.4 Decompress.RTPrefs 3.2 The Main Window 3.2.1 Gadgets 3.2.1.1 Control Panel 3.2.1.2 Misc. Panel 3.2.1.3 Position Panel 3.2.1.4 Volume Panel 3.2.1.5 Tempo Panel 3.2.2 Menus 3.2.2.1 Project Menu 3.2.2.2 Settings Menu 3.2.2.3 Control Menu 3.3 The Prefs Window 3.3.1 Gadgets 3.3.1.1 Defaults Panel 3.3.1.2 F/X Panel 3.3.1.3 Timing Panel 3.3.1.4 Bootup Panel 3.3.1.5 Default MOD Path Panel 3.3.1.6 Port Panel 3.3.1.7 Confirm Panel 3.3.2 Menus 3.4 The About Window 3.4.1 Gadgets 3.4.2 Menus 3.5 AREXX Commands 4 The Player 4.1 AREXX Commands 5 The Libraries 5.1 DESTracker 5.2 RexxHost 6 Credits 7 The Future 8 Index 9 Disclaimer Copyrights RTracker 2.0 and RTInterface 2.0 are Copyright (c) 1991, 1992 Mike R. Manzano, All Rights Reserved. DESTracker.Library is Copyright (c) 1992 Darren Schebek, All Rights Reserved. RexxHost.Library was created and put in the Public Domain by Olaf Barthel. RTracker and RTInterface is SHAREWARE. This archive is freely distributable. If you use this program often, please send n American dollars (or the equivalent in your local currency) to: Mike R. Manzano RT/Basic 10949 Hillsboro Dr. NW Silverdale, WA 98383 Registered users will receive a hard copy version of the manual, and a full release disk. Registered users will also receive other RTracker modules (a Scope program with configurable VU meters, and a spectrum analyzer; a multi-module selector, with options for programmed or random play, etc.) on the same disk, and will be notified when other modules are to be released. I realize that by putting this program out as ShareWare, I will receive a lot less than if I had put it out commercially, but I wanted to make it affordable for everyone to use without going through a lot of hassle. I did not just put an arbitrary price on this software; I asked many people for their opinion on what the software is worth, and used the most common answer. So now I am BEGGING you on my hands and knees to register this software. I'm going through college right now, and could always use the money. Preface For quite a while, I have been looking for the perfect MOD player to suit all my needs. It had to be small, easy to use, highly configurable, and invisible. By invisible, I mean that the user shouldn't have to think when operating the interface; it should be obvious what everything does. Ed Mackey's EDPlayer has come (by far) the closest to perfection. However, two of the most annoying aspects to using a MOD player is the lack of configurability, and the sometimes too-flashy, unstandard interfaces. My answer to these problems (and others) is RTracker. Because RTracker has been programmed in a modular fashion, it can be easily configured to meet the end user's need; essentially giving you, the user, the power to create your own "perfect" MOD Player. RTracker was not written with just my needs in mind, but with everyone's needs in mind. That's one of the reasons that RTracker has already gone through multiple revisions. RTracker's interface, RTInterface, has the look and feel of a normal AmigaDOS program, and attempts to use all standards set by Commodore's style guide. The interface is just that - an interface. There aren't any fancy VU meters, spectrum analyzers, counters, and so forth. That's left to another program to do. It supports automatic decompression of MODs, which saves disk space, and eliminates the need to manually decompress MODs. RTracker itself is only a window; you can't control it from anything but AREXX. This is perfect for those users who would like to play MODs in their multimedia presentations, but don't want their memory and processor taken up by snazzy, but otherwise useless graphics. Also, because RTracker uses a shared library to play it's MODs, one simply has to replace the library with newer versions to take advantage of newer MOD formats. RTracker, RTInterface, and other RTracker modules are the product of many people's ideas, recommendations, and ideals. I hope you enjoy the result. If you have an idea that would make RTracker easier to user, feel free to write me at my address above. I'll do my best to incorporate them into a future revision. Now, you might be asking yourself, "why all this for a MOD program? Why not do this with something really useful, like a paint program, or a Word Processor?". Well, that's due to several facts. First, it would take much more time than I have to program something large like that. Second of all, I am 100% certifiably insane with delusions of grandeur. Ahahahahah!!! MOD Players are my life!!! Ahahahaha!!! I am a MOD Player!!! Ahahahahaha! Um, anyway, on with the program. 1 Installation Section 1 describes how to install the RTracker distribution, and make it runnable. RTracker will not function correctly until it has been installed properly. WARNING: Running the program without installation may be hazardous to your health. Please make sure you install it properly before running. 1.1 The Install Program The installation program used is Commodore's standard Installer program, so the process should be familiar to those of you that have used it before. The prompts and help function should be self explanatory. The installer will do the following modifications to your system disk (not in any order): * It will create a directory with the name and location of your choice. * RTracker and various support files will be copied into that directory. * The assign "PREFS:" will be added to the s:User-Startup. * The libraries Destracker.library and RexxHost.library will be copied to your LIBS: directory if (1) they don't yet exist there, or (2) the version already installed there is an older version. * Depending on if and where you have certain file decrunchers, the installer will automatically configure RTInterface to use those decrunchers. At this point, the installer will attempt to modify the Decompress.RTPrefs file for LHa compression, and PowerPacker compression. * The installer will ask you for your default MOD directory, and modify RTPrefs to use that. * You will be prompted to create a new directory where all decompression will take place. See section 1.2.4. 2 Introduction Welcome to RTracker, the first user-configurable, modular, standard 2.0ish, and otherwise easy-to-use MOD player. First, what exactly is a MOD? MOD, which is the short form of MODULE, is a music file format that was created to make programming music for games and demos easier and less time consuming. There are a multitude of programs that will output this format. The four major ones are SoundTracker, NoiseTracker, StarTrekker, and ProTracker. The programs, or Trackers, as they have come to be called, are music sequencers. Because of the quality of sound of these musical compositions, people have started to listen to them separately from the games and demos, and even started creating their own just to listen to. The popularity of MODs has become so great that the standard Amiga song format, SMUS, is possibly no longer the most widely-used format. Of course, you can't listen to MODs unless you have a program to play them. Since then, people have created many different MOD players; but none of them really attempted to be completely system compatible and standardized. With the introduction of the 2.0x operating system, standardization became a significant subject. RTracker attempts to follow those standards while being flexible enough that the users can customize it. RTracker is the result of many people's ideas of how a MOD player should operate. Among it's many features are: * Default MOD path selection, so MODs can be accessed easily. * Automatic decompression of multiple compression formats. Automatic decompression can be set up to use any compression programs that you own or use. * A modular architecture. You need not take up precious memory with options and gauges that serve no function to you. * A standard 2.0 interface, and full compatibility with 2.0x. It has even been tested on 2.1 and 3.0x systems. * Full AREXX support. In fact, the main communications protocol used when the modules interact is AREXX. * Full configurability. I tried not to assume anything when creating the player. * Program support. I promise to put out timely upgrades, and will attempt to integrate your ideas with the system. How exactly does RTracker work? RTracker is actually composed of two programs - the RTracker player, and an RTracker external module named RTInterface. RTracker is simply a window with an AREXX port, and nothing else. It is the heart of all the collective modules, although it as well can be replaced. RTInterface is where the average user can take advantage of RTracker's features. Due to the fact that RTInterface can automatically load and unload RTracker and other modules, you can consider RTracker and all its external modules as one program. This manual will describe in-depth how RTracker and its modules work together. 3 The Interface RTInterface is a GUI (Graphics User Interface) specifically designed to communicate and command the player in a logical and easy to use manner. Although the interface doesn't take full advantage of all the features in the player module, the range of functions it has is more than enough for an average user. 3.1 The Script Files RTInterface uses four different script files to function properly, two of which are created at install time. All script files are easily editable with a standard text editor. RTLoad.script is a standard script file that RTInterface executes on bootup. RTQuit.script is a standard script file that RTInterface executes upon shutdown. RTPrefs is a self-documented ASCII file that describe's RTInterface's preference settings. Decompress.RTPrefs describes your external compression formats. 3.1.1 RTLoad.script RTLoad.script is an AmigaDOS script file that RTInterface will execute upon bootup. These programs can be anything you want, but typically, you'll want to run RTracker Modules here. The current script is as follows: .key path ; RTInterface script to autoload some modules ; path is the current default path in RTPrefs. ; WARNING: Make sure you handle all cases where the file name has ; a space in it! (Such as "The File Name"). Either don't ; use spaces in your file name, or use quotes. ; Load RTracker "RTracker" When the script is run, the current RTracker path (the path where all RTracker modules exists, along with all the support files, except for possibly RTPrefs) is passed into the variable "path". Comments are specified by including a semi-colon before the comment. As you can see, only one command is executed: "RTracker" This command runs RTracker from the current path. The "path" variable always ends with the proper terminating character - either a colon, or a slash - so you shouldn't include one in your command. Also, notice that the command is encased in quotes. This provides for the possibility that the pathname contains spaces. As you may already know, AmigaDOS requires that there not be any spaces in a filename unless the filename is encased in quotes. Another thing to keep in mind is that RTInterface will not continue until the script file has finished executing. Make sure the commands that you put in here either release the CLI, or incorporate redirection to NIL:. As an example of the latter, say you have a program called LScope, and that LScope doesn't release the CLI on bootup. The entry for LScope would be: "LScope >NIL: LScope >NIL: ..." Of course, it is always safe to redirect whether the program releases the CLI or not. If you are unsure about whether or not a program releases the CLI, redirect to NIL:. 3.1.2 RTQuit.script RTQuit.script is similar to RTLoad.script in that it is also an AmigaDOS script file. Therefore, if follows that RTQuit.script follows all the same rules as RTLoad.script. Please read the RTLoad.script section (3.1.1) for auxiliary uses of RTQuit.script. The main use of RTQuit.script is to tell the programs that were previously loaded with RTLoad.script to quit. This implies that the programs you run must be terminable externally from the CLI. Otherwise, the user must manually click on an close gadget to get rid of it. The current RTQuit.script is as follows: .key path ; RTInterface script to unload programs ; path is the default path (usually where programs are) ; WARNING: Make sure you handle all cases where the file name has ; a space in it! (Such as "The File Name"). Either don't ; use spaces in your file name, or use quotes. ; Unload RTracker rx "address 'RTracker';quit" As you can see, the only command executed is: rx "address 'RTracker';quit" This runs the program rx (the AREXX interpreter), tells it to talk to the port 'RTracker' (which is RTracker's AREXX port), and then gives RTracker the command to quit. It is important to note that if you don't put quotes around the port name, AREXX will automatically capitalize the name, and the port name is case sensitive. Putting quotes is always a good idea. The command to quit from your own program is up to you; this manual can't possibly document all possible programs, and their methods of quitting. Refer to your program's manual for further instruction. 3.1.3 RTPrefs RTPrefs is the main preferences file for RTInterface. It is a plain ASCII text file that describes how RTInterface should act. An example RTPrefs follows: 128 Auto Play 128 Decompress 0 Auto Detect PAL/NTSC 128 Request on Eject 0 NTSC/PAL default switch; NTSC = 0, PAL = 1 0 Filter on/off 128 Repeat at end 128 Auto Load Rtracker player program on bootup 128 Auto Unload RTracker player program on shutdown 128 Request on Bootup Work:RTracker Tracks: Unused All the entries except for the last three are composed of a left-aligned number field followed by an optional comment. A number other than zero specifies that this option should be turned ON, and a zero specifies that the option should be turned OFF. The last three fields are strings; the first two are path names, and the last is unused. The first entry, Auto Play, tells RTInterface whether or not to start playing the MOD once you load it, regardless to whether or not you clicked on the PLAY gadget. The Decompress entry will disable/enable automatic decompression. See section 3.1.4 for more information about this topic. Auto Detect PAL/NTSC tells RTInterface to automatically determine the correct timing for a MOD. This will only work for MODs with the special DesTracker timing information imbedded in the MOD. Registered users will receive this program when it is completed. Unless you have this program, or a program that will save it in this format for you, such as Darren Schebek's DTC program, it is a good idea to disable this option. Request on Eject specifies whether or not RTInterface should request you for another file name when you eject the currently loaded MOD. The NTSC/PAL default switch only takes effect if Auto Detect PAL/NTSC is deactivated. Upon bootup, and upon loading a new MOD, this entry is examined to see what timing the MOD should use. Filter ON/OFF specifies whether or not the filter should be activated upon loading a new MOD into memory. Repeat at end will tell RTInterface whether to loop back to the beginning of the song when the current play sequence is completed. If this is not activated, the player will stop playing at the end of the song. Auto Load specifies whether or not RTInterface should execute the RTLoad.script file upon startup. Auto UnLoad specifies whether or not RTInterface should execute RTQuit.script upon shutdown. Request on Bootup specifies whether or not RTInterface should request you for a file name immediately after the bootup sequence is finished. The first string entry, the RTracker path (the one that says Work:RTracker in the example), specifies where the support files (all the scripts bar this one), RTracker, and RTracker modules are stored. This is the path name that is passed to the variable in the RTLoad.script and RTQuit.script script files. See sections 3.1.1 and 3.1.2 for more information. The second string entry, the default MOD path, is the path that RTInterface will automatically lock on to when presenting you with a file requester. The third string field is, as of yet, unused. Ignore this field, but leave it there. Please note that there should be no comments on the entries that contain strings. 3.1.4 Decompress.RTPrefs Out of all the script files, the Decompress.RTPrefs script is the most cryptic, but you'll find after looking at it closely, it isn't cryptic after all. When you installed RTracker, the file was created for you, with up to two entries. These entries (one per line) describe to RTInterface how it should handle decompressing certain files. The two that may have been installed are LHa, and PowerPacker's Decrunch utility. The file is in this format: ||| ||| ||| ... @ If you did not have both LHa and Decrunch, or chose not to install them, the file should contain only the at-sign (@). The at-sign tells RTInterface that it has reached the end of the file. The best way to illustrate it's use is to give an example. Take the following example Decompress.RTPrefs: #?.LHA|c:lha >con:0/0/500/100/Decompressing e "%" Work:RTracker/|Work:RTracker| #?.pp|c:decrunch >con:0/0/500/100/Decompressing "%" Work:RTracker|Work:RTracker| @ Take note that each entry must exist on one, and only one, line. The above example may be misleading because the entries may have been split into two lines by the word-processor that this manual was created on. There should be no blank lines between each entry. Each section of each entry is terminated by a vertical bar (|). The first section, (the #?.LHA in the first entry of the example), tells RTInterface how to recognize an archived file. This string can be any valid AmigaDOS filename/wildcard combination. The second section, , is the actual command that RTInterface will run to decompress a file. Wherever a percent sign (%) appears, RTInterface will insert the file name of the compressed file. It is a good idea to put quotes around it in case the file name has a space in it. When specifying a command line to execute, keep the following in mind: * It is very important to make sure that the command you specify will put the resulting decompressed file into the Decompress directory that you specified upon installation. If you choose not to decompress to your standard Decompress directory, make sure that the directory you specify is empty, or that the contents of that directory can be deleted. RTInterface will automatically delete the contents of this directory before decompression. * If your decompression program is not in your current path, be specific as to where it is by prepending the path to the command. The last section, , specifies the directory where RTInterface will find the resulting decompressed file. Also note that compressed files will should not include anything but the MOD file. There should be no extraneous files in the archive. This will be changed in the registered version of RTracker to be smarter about detecting what is a MOD file and what is not. Make sure that there are no extraneous spaces in the entries (no spaces before or after the vertical bar, and no spaces where not needed). RTInterface may choke if there are. 3.2 The Main Window RTInterface's Main Window is where all the control gadgets are found. When you first boot up RTInterface, you will be presented with the Main Window. The Main Window is also an APPWindow. Simply dumping icons from the Workbench onto the main window will load the MOD into memory, and optionally decompress and play the MOD. It works the same as if you had clicked on the Load gadget. 3.2.1 Gadgets For the most part, you will be using RTInterface's gadgets to manipulate the MOD in memory. The following five sections (3.2.1.1 - 3.2.1.5) will describe the different gadgets by their groupings (or "panels"). A note about string gadgets: All string gadgets are connected to each other. Pressing the TAB key while in a string gadget will move the cursor to the next string gadget. Pressing SHIFT TAB will move the cursor to the previous string gadget. Slider and Scroller gadget arrows may be used to move the slider left and right. If you hold the arrow gadgets down for a few seconds, the they will auto-repeat. 3.2.1.1 Control Panel The Control Panel is located in the upper-left hand corner of the Main Window. It is comprised of five gadgets that control the flow of music being played. These gadgets are (in order from upper left to bottom right): Load, Eject, Stop, Play, and Pause. To play a song, you must first load it into memory. The Load gadget will open a standard system file requester, which you may then use to select a module to load. The file requester will automatically be positioned to your default MOD path. Upon selecting a module, any decompression that needs to be done will be performed. If your prefs specify to automatically play the song after it's loaded, it will then proceed to do so. For more information on the system file requester, please read the manuals that were included with your AmigaDOS distribution. To remove a song from memory, and to free that memory up, you may click on the Eject button. Again, depending on your prefs, a file requester will appear to prompt you for your next selection. Stopping a song in mid-play can be accomplished by hitting the Stop gadgets. The song will stop playing, but will not be unloaded from memory. You may not continue the song where you left off after pressing Stop in all cases except for one. See the Pause command for more information. If you press Stop while within Pause mode, Pause will be cancelled, and the player will stay in Stop state. The Play button serves two functions. If a MOD has just been loaded into memory, or Stop has been pressed, Play will start playing the song from the beginning. If you press Play while Pause mode is in progress, the player will drop out of Pause mode and continue where you Paused it. Pause has two functions, one of which is a special case and is used with the Stop gadget. Pressing Pause while a song is playing will drop the player into Pause mode. All music will stop. Pressing Pause again while in Pause mode will cause the player to continue Play where you left off. Earlier it was stated that the effect of stopping a song would cause the player to start over from the beginning. If you decide that you would like to continue after pressing Stop after all, double-click Pause. This will have the effect of continuing Play where you left off. 3.2.1.2 The Misc. Panel is located in the upper right-hand corner of the Main Window, just under the Volume Panel. It is comprised of three checkbox gadgets, three buttons, and one cycle gadget. The three checkbox gadgets are: Help, Filter, and Loop. The three button gadgets are: About, Prefs, and Refresh. The cycle gadget is a switch between PAL and NTSC. The first checkbox gadget, Help, causes RTInterface to go into Help mode. To use this feature, click on the Help gadget until a checkmark appears in it's box. Until you click on the Help gadget again, any other gadget that you click will open a window stating the respective gadget's functions and/or how to use it. To deactivate Help mode, simply click on the Help gadget until the checkmark goes away. The second checkmark gadget, Filter, toggles the Amiga's internal filter on and off, as well as the power LED. Some older Amigas don't support this feature. To enable looping, activate the Loop gadget. Looping has the effect of starting the song over when it has played through. If looping is not activated, the player will go into Stop state after the song is done. The first button, About, will open the About Window. This displays information about RTInterface. For more information on the About Window, see section 3.4. The second button, Prefs, will open the Prefs Window. Here, you will be able to modify your preferences. For more information on the Prefs Window, see section 3.3. If some other program sends RTracker an AREXX command, such as Stop, the player will comply and do so without RTInterface's knowledge. The interface will think that RTracker is still playing. Whenever the player and the interface get out of sync, pressing the Refresh gadget will fix it. A Refresh is automatically executed if some another program tells RTracker to Load a new song. The last gadget in the Misc. Panel is the Timing cycle gadget. Clicking on this gadget has the effect of switching between PAL and NTSC. 3.2.1.3 Position Panel The Position Panel is located right under the Misc. Panel. It is comprised of six gadgets. The gadgets are (in order): Position string gadget, Fast Rewind, Fast Forward, Slow Rewind, Slow Forward, and Position slider. All the above mention gadgets work synchronously. The Fast Rewind and Fast Forward gadgets will move the player one block backward (one block is usually comprised of 63 musical events) or one block forward, respectively. The Slow Rewind gadget will put the player about 5 musical events earlier. The Slow Forward gadget will increase the player speed significantly for a few seconds - in effect, forwarding the play sequence. If you would like to explicitly tell the player what block to jump to, you can enter it in the Position string gadget. Press return, TAB, or SHIFT TAB will execute the jump. The slider gadget can be used to manually position the currently playing block. The slider gadget and the text display to the left also have an added function: They also update to tell you where in the current MOD you are. The slider also auto-sizes itself to be proportionally correct in it's container. 3.2.1.4. Volume Panel The Volume Panel is located at the top of the Main Window, directly below the Main Window title bar. It is comprised of one standard scroller gadget and string gadget. Moving the scroller gadget left and right will modify your MOD's volume. Moving the slider to the left will decrease the volume, while moving it the opposite way does the exact opposite. To the left of that gadget is the a string gadget where you can specifically specify the volume. Valid volume values (hey - is that a tongue twister or what?) range from 0 to 63, 63 being the loudest. 3.2.1.5 Tempo Panel The Tempo Panel is located at the very bottom of the Main Window. It is comprised of two scrollers and their respective string gadgets. The Coarse Tempo scroller allows you to change the tempo of the current MOD. This slider actually changes the delay value between events. A value of zero (the middle of the slider) specifies the normal tempo, which is either standard PAL or standard NTSC, depending on what you have it set to. The more negative your value is, the faster the mod will go. The converse is also true. Valid values for the string gadget range from -16 to 15, -16 being the fastest, 15 being the slowest. The Fine Tempo scroller is exactly the same as the Coarse Tempo scroller except for the fact that it is used to fine-tune the current Coarse Tempo. Valid values for the string gadget range from -128 to 127. A value of zero specifies the exact Coarse Tempo setting. 3.2.2 Menus There are three separate menus: Project, Settings, and Control. They are an alternate method of operating the interface, and also provide for command keys. Command keys are a keyboard short-cut method of operating the interface. See your Amiga manual for more information on command keys. 3.2.2.1 Project Menu The Project Menu is located in the left-most corner of the menu strip. It is comprised of five menu items: Load, Eject, Prefs, About, and Quit. The Load, Eject, Prefs, and About menu items are exactly equivalent to their respective gadgets on the Main Window. For more information on Load and Eject, see section 3.2.1.1. For more information in Prefs and About, see section 3.2.1.2. The Quit gadget is equivalent to hitting the close box in the upper right hand corner of the Main Window. It has the effect of exiting the program, and possibly executing the RTQuit.script script file. 3.2.2.2 Settings Menu The Settings Menu is located in the middle of the menu strip. It is comprised of four menu items: PAL, Filter, Loop, and Help. All four items are toggle items. Filter, Loop, and Help have the same functions as their gadget equivalents in the Main Window. The PAL functions exactly the same as the PAL/NTSC cycle gadget in the Main Window. For more information on these functions, see section 3.2.1.2. These menu items are connected to their respective gadgets. Changing the state of the menu or the gadget will also modify the object's significant other. 3.2.2.3 Control Menu The Control Menu is located to the right of all the menus in the menu strip. It is comprised of three menu items: Stop, Play, and Pause. All three items are exactly equivalent to the gadgets in the Control Panel with the same name. For more information on these functions, see section 3.2.1.1. 3.3 The Prefs Window The Prefs Window is accessible from the Main Window's Misc. Panel. It contains seven different panels. The panels are: Defaults, F/X, Timing, Bootup, Default MOD Path, Port, and Confirm. Using these panels, you can set RTInterface to function the way you want it to. All of the options in the Prefs Window have an equivalent in the RTPrefs file. For more information on RTPrefs, see section 3.1.3. 3.3.1 Gadgets The following seven sections (3.3.1.1 - 3.3.1.7) will describe the different gadgets by their groupings (or "panels"). A note about string gadgets: All string gadgets are connected to each other. Pressing the TAB key while in a string gadget will move the cursor to the next string gadget. Pressing SHIFT TAB will move the cursor to the previous string gadget. 3.3.1.1 Defaults Panel The Defaults Panel is located in the upper left corner of the Prefs Window. It is comprised of four checkbox gadgets. Using these gadgets, you can specify how RTInterface will operate. The AutoPlay option allows you to specify whether or not the player will automatically play the MOD right after loading and decompressing. The Decompress option specifies whether RTInterface will attempt to decompress an archived file when it encounters one. The AutoDetect PAL/NTSC option specifies whether or not RTracker will try to load timing information from a MOD. Unless you have a MODs with this embedded information in them, this should be turned off. When this function is on, the Timing prefs located in the Timing Panel will have no effect. If you would like the interface to prompt you for a MOD after an Eject, activate the Request on Eject function. 3.3.1.2 F/X Panel The F/X Panel is located in the upper portion of the Prefs Window in the center. It is comprised of two checkbox gadgets: Filter and Loop. The F/X Panel will allow you to set the defaults pertaining to different audible effects. If Filter is activated, the filter will be turned on every time a new MOD is loaded. If Loop is activated, the loop checkbox on the Main Window will be automatically activated upon loading a new MOD. 3.3.1.3 Timing Panel The Timing Panel is located in the upper right corner of the Prefs Window. It is comprised of one set of mutually exclusive gadgets. Selecting one or the other will affect the PAL/NTSC cycle gadget in the Main Window. The PAL/NTSC cycle gadget will be set to the selection in this panel whenever a new MOD is loaded into memory. Note that this function is disabled if AutoDetect PAL/NTSC is activated in the Defaults Panel. For more information on the PAL/NTSC cycle gadget, see section 3.2.1.2. For more information on the AutoDetect PAL/NTSC option in the Defaults menus, see section 3.3.1.1. 3.3.1.4 Bootup Panel The Bootup Panel is located in the middle of the Prefs Window. It is comprise of three checkbox gadgets, one string gadget, and a directory requester gadget. The three checkbox gadgets are: AutoLoad, AutoUnload, and AutoRequest. The string gadget is the RTracker Directory gadget. The Bootup Panel is used to set the defaults dealing with bootup. If the AutoLoad checkbox gadget is activated, the RTLoad.script file will be executed upon bootup of RTInterface. For more information on RTLoad.script, see section 3.1.1. If the AutoUnload checkbox gadget is activated, the RTQuit.script file will be executed upon shutdown of RTInterface. For more information on RTQuit.script, see section 3.1.2. The RTracker Directory string gadget must contain the path where RTracker, RTracker's modules, and RTInterface's support files are kept. Otherwise, RTInterface won't be able to find anything. The directory gadget to the right of the string gadget will bring up a requester to let you choose a directory automatically. You selection will be inserted into the RTracker Directory string gadget. 3.3.1.5 Default MOD Path Panel The Default MOD Path Panel is located directly under the Bootup Panel in the Prefs Window. It contains only two gadgets. The string gadget in this panel is used to store your default MOD Path. RTInterface will default to this path when asking for a MOD. The file requester gadget to the right will insert your selection into the string requester. 3.3.1.6 Port Panel The Port Panel is currently unused. Leave it alone, and don't bother it. It doesn't like to be disturbed. Warning: If you play with this string gadget and it physically hurts you, it is not my fault. I warned you. 3.3.1.7 Confirm Panel The Confirm Panel is at the bottom of the Prefs Window. It is not labelled. There are three gadgets in this panel. The first gadget, Help, causes RTInterface to go into Help mode. To use this feature, click on the Help gadget until a checkmark appears in it's box. Until you click on the Help gadget again, any other gadget that you click will open a window stating the respective gadget's functions and/or how to use it. To deactivate Help mode, simply click on the Help gadget until the checkmark goes away. The last two buttons, Cancel and Okay should be self explanatory. Cancel will abort any changes to your preferences and exit the preferences editor. Clicking on Okay will modify your prefs, and modify the RTPrefs file to reflect the changes. For more information on RTPrefs, see section 3.1.3. 3.3.2 Menus There is only one menu in the Prefs Window, the Prefs Menu. The entries are: OK, Help, and Cancel. These functions are equivalent to their Confirm Panel counterparts. See section 3.3.1.7 for more information on these menu items. 3.4 The About Window The About Window is a small window that displays various pieces of information. 3.4.1 Gadgets The only gadget in the About Window is the OK Gadget. Clicking on this or the off gadget will exit the About Window. 3.4.2 Menus Whatever you do, don't tickle it. 3.5 AREXX Commands RTInterface supports a few different AREXX commands. For the most part, the average user will not have to use them. RTInterface's AREXX Port is "RTracker", case sensitive. The AREXX commands follow. They are all case sensitive. 'quit' - quits RTInterface 'tick' - used primarily by RTracker. This tells RTInterface to refresh it's position slider gadget. For more information on the position slider gadget, see section 3.2.1.3. 'refresh' - used primarily by RTracker. This tells RTInterface to do the equivalent of pressing the Refresh gadget. For more information on the Refresh gadget, see section 3.2.1.2. 4 The Player The Player, RTracker, is the heart of the whole system. It contains all the code to do effects, and so forth. Although it has no interface, it has a good size command set which is growing every day. The next section will document those AREXX commands. When run, RTracker will open a small window. It will always display it's current status in this window. 4.1 AREXX Commands RTracker's command set contains many synonym commands that attempt to make it compatible with Ed Mackey's EDPLAYER, and RTracker 1.0. denotes an optional argument <> denotes a required argument 'goodbye', 'quit', 'kill' Tells RTracker to clean up and die. 'playsong', 'play' Tells RTracker to play the currently loaded MOD. It takes one optional parameter, a file name. If you supply a MOD's file name, that MOD will be loaded first. 'contsong', 'cont' Continue play from where you last left off. 'stopsong', 'stop', 'paus' Stops the current play sequence. 'changetempo', 'tempo' Changes the current coarse tempo setting. Valid values are -16 to 15, zero being the base speed (either NTSC or PAL, depending on which you have set as the base speed). The smaller the number, the faster the tempo. 'about' - Displays some version info in the RTracker window. 'autodetect' - Turns MOD timing automatic detection on or off. See the Auto Detect PAL/NTSC subsection in section 3.1.3 for more information on this feature. 'changeftempo', 'ftempo' - Same as 'changetempo' and 'tempo', but with the difference that this sets fine tempo. The base speed is the current Coarse tempo. Valid values are -128 to 127, zero being the base value. 'dvolume', 'dvolu' <> - Change the volume relative from the current volume. If you specify a value too big or too small, RTracker will catch it and use a value that will stay within the proper bounds. 'fadedelay' <> - Set the fade delay value. The path is required. Fade values can range from 0 to 31, inclusive, 0 being very fast, 31 being very slow. 'fadedown' - Fades the song down from the current volume regardless of whether or not Fade Mode is on. After it's done, it will set Fade Mode off. The optional argument is the fade delay rate. See the 'fadedelay' command for information on the delay rate. 'fadeoff' - Turns Fade Mode off. 'fadeon' - Turns Fade Mode on. If this is activated, sending Stop or Play to RTracker will fade the song volume down or up, respectively. 'fadeup' - Fades the song up from zero volume regardless of whether or not Fade Mode is on. After it's done, it will set Fade Mode off. The optional argument is the fade delay rate. See the 'fadedelay' command for information on the delay rate. 'fblock' - Jump forward one block. 'filter' - A value of 1 will activate the Amiga's built in sound filter. A value of zero will turn it off. 'jump' <> - Jumps to block <> in a MOD. 'loadsong', 'load' <> - Loads a new MOD from disk. The parameter is required to load a MOD. 'menu', 'front' - If the argument is non-zero, RTracker's window will come to the front. If the argument is zero, RTracker's window will be pushed to back. 'rblock' - Jump backward one block. 'repeat' - Repeat will play the MOD times before stopping. A value of zero tells RTracker to continually repeat. 'repend' - A value of 1 will turn repend on. A value of 0 will turn repend off. If repend is activated, when the song is finished playing, the player will jump back a block, and replay it while fading the song. 'restorevol' - If you've messed up the volume by fading and so forth, restorevol will fix it. 'rline' - Jump backward a few events. 'scarce', 'eject' - Unloads the currently loaded MOD. 'self' - Short for self destruct. Sending this to the RTracker will immediately fade the song and then kill RTracker. The optional argument is the fade delay rate. See the 'fadedelay' command for information on the delay rate. 'timing' - Sets the base timing of the MOD. A value of 0 denotes NTSC, a value of 1 denotes PAL. 'volume', 'volu' <> - Changes the volume. Valid values range from 0 to 63, 63 being the loudest. 5 The Libraries RTracker and RTInterface use two libraries for some of its functions. RTracker uses DesTracker.Library, and RTInterface uses both DesTracker.Library and RexxHost.Library. 5.1 DESTracker The DesTracker library is what RTracker uses to play MODs. Throughout the development of RTracker, I've used many different methods of handling module data. Version 1.0 of RTracker didn't even support SoundTracker type files; only MED files. This didn't sit will with me, so I then moved on and implemented my own in assembly language. I didn't like that either. After months of searching for MOD format information, I finally found an ideal choice. That choice was the Darren Schebek's DesTracker library. Because DesTracker is a library, it can easily be replaced to support more MOD, or even MED formats (are you listening, Darren? ;). It is also very compatible with the new Amiga operating system(s). 5.2 RexxHost The RexxHost library is what RTInterface uses to implement an AREXX port. Before I got this library, the AREXX port was implemented using the minrexx distribution. RTracker uses minrexx, while RTInterface uses the RexxHost.library. They are both very good, and very compatible; I'm not sure yet which one I like better. RexxHost does, however, have a definite advantage: it's a shared library. Most likely, RTracker will be re-written to use the RexxHost library. 6 Credits I'd like to take this change to thank my beta testers, and all the people who have given me their opinions and critiques of the program. Their names follow. The C-SIG gang - Charlie Johnson Forrest Towne Ed Musgrove Adolf Weindanz My official RTracker BBS support board sysops: Jim Lynch Keith Thibodeaux Larry Cloud The library authors: Darren Schebek Olaf Barthel And the following people for their ideas and input that had a direct impact on this revision: Trev Dagley Matt Splett David Radke Nick Salvatico Michael Mac Ness Daniel Lehenbauer I'd also like to thank Commodore for an excellent machine. I hope in the future that I can say the same about Commodore ;). 7 The Future Hopefully, RTracker will grow and become the best MOD Player out on the market. I can't promise that it will be, but I can certainly guarantee that if you keep those comments rolling in, I will make it a priority to incorporate your idea of perfection into a future revision. Future improvements to the current software: * More support for different types of modules. * Selection of MODs within an archive without having to decompress the whole thing. * Support for fading in RTInterface. * Iconification of RTInterface into an APPIcon. * Making RTracker into an APPWindow. Future RTracker modules to be released are: RTMultiPlayer - a fully programmable multi-MOD loader and player, supporting fades and so forth, as well as a scripting language or a GUI interface with options for programmed or random play. Possibly double buffering of MODs. RTIcon - a small Interface module that opens an APPIcon that you can dump MODs into. RTEffects - a module to do special effects with modules. Don't know about this one. Opinions? Comments? Blah? 8 Index 9-10 9 6-7, 9 9-10 AREXX 1, 3, 5, 7, 12, 17-18, 20 AREXX Commands 1, 17-18 arrows 11 at-sign 9 Auto Detect PAL/NTSC 8, 18 Auto Load 8 Auto Play 8 Auto UnLoad 8 block 12-13, 19 Bootup Panel 1, 16 Cancel 17 Coarse Tempo 13, 18 comments 6, 9, 21 Confirm Panel 1, 16-17 Contents 1, 10 Control 1, 3, 10-11, 13-14 Control Menu 1, 14 Control Panel 1, 11, 14 Copyright 1-2 Credits 1, 20 Decompress 1, 3-4, 6, 8-10, 15, 21 Decompress directory 10 Decompress.RTPrefs 1, 4, 6, 9 decompression 3-5, 8, 10-11 Default MOD Path Panel 1, 16 Defaults Panel 1, 15-16 DESTracker 1-2, 4, 8, 20 DESTracker.Library 2, 4, 20 DTC 8 EDPlayer 3, 18 F/X Panel 1, 15 Fade Mode 19 Filter 8, 12, 14-15, 19 Fine Tempo 13, 18 Forward 12-13, 19 Gadgets 1, 10-17 Help 4, 12, 14, 17 Installation 1, 4, 10 Installer 4 Introduction 1, 4-5 LHa 4, 9-10 Libraries 1, 4, 20 LIBS: 4 Load 5-6, 8, 10-12, 14-15, 19 Main Window 1, 10-15 Menus 1, 13-14, 16-17 Misc. Panel 1, 12, 14 MOD 1, 3-5, 8-11, 13-16, 18-21 MOD path 1, 5, 9, 11, 14, 16 NIL: 6-7 NTSC/PAL default switch 8 Okay 17 panels 10, 14-15 player 1, 3-5, 8, 11-13, 15, 18-19, 21 Port Panel 1, 16 Position Panel 1, 12 PowerPacker 4 Preface 1, 3 Prefs Menu 17 PREFS: 4, 9 Project 1, 13-14 Project Menu 1, 14 Repeat at end 8 Request on Bootup 8-9 Request on Eject 8, 15 Rewind 12-13 RexxHost 1-2, 4, 20 RexxHost.library 2, 4, 20 RTInterface 2-10, 12, 14-17, 20-21 RTLoad.script 1, 6-9, 16 RTPrefs 1, 4, 6-7, 9, 14, 17 RTQuit.script 1, 6-7, 9, 14, 16 RTracker 2-10, 12, 15-21 RTracker path 6, 9 Scope 2 Scroller 11, 13 Settings 1, 6, 13-14 Settings Menu 1, 14 Slider 11-13, 17 Slow Forward 12-13 Slow Rewind 12-13 spectrum analyzer 2-3 Tempo Panel 1, 13 The About Window 1, 12, 17 The Future 1, 21 The Install Program 1, 4 The Interface 1, 3, 5, 12, 14-15 The Libraries 1, 4 The Main Window 1, 10-15 The Player 1, 5, 8, 11-13, 15, 18-19 The Prefs Window 1, 12, 14-17 The Script Files 1, 6, 9 Timing Panel 1, 15 User-Startup 4 vertical bar 10 Volume Panel 1, 12-13 VU meters 2-3 9 Disclaimer Boy, do I hate these things. I'll make it short. If this software totally screws up your system, it's not my fault. Use at your own risk. I'm not, of course, saying that it will. Just... in case?