Frozen Fish 1: Amiga

home *** CD-ROM | disk | FTP | other *** search

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d7xx / d748 / delitracker.lha / DeliTracker / Docs / DeliTracker.doc < prev next >

Wrap

Text File | 1992-10-12 | 36KB | 868 lines

*************************************************************************** * DeliTracker * *************************************************************************** © 1992 by Delirium $VER: V1.30 (22.09.1992) 1. CONTENTS 1.CONTENTS 2.LICENSING AND DISTRIBUTION 3.INTRODUCTION 3.1 What is DeliTracker ? 3.2 Why use DeliTracker ? 4. GETTING STARTED 4.1 System requirements 4.2 Starting from CLI/Shell 4.3 Starting from Workbench 4.4 Installation 5. BASICS 5.1 Player 5.2 Packed modules 5.3 Kickstart 2.0 5.4 Options 5.5 Configuration files 6. HOW TO CONTROL DELITRACKER 6.1 The main window 6.1.1 Gadgets 6.1.2 Menus 6.1.3 Shortcuts 6.2 The preferences window 6.2.1 Gadgets 6.2.2 Shortcuts 6.3 ARexx 7. TROUBLESHOOTING 8. THE FUTURE OF DELITRACKER 9. ACKNOWLEDGEMENTS 2. LICENSING AND DISTRIBUTION DeliTracker (c) 1992 by Peter Kunath and Frank Riffel. This Program is Shareware. If you like this program and use it frequently, we encourage you to register. The shareware fee is $US 20 or 20 DM. You may send CASH or EUROCHEQUE's. We cannot accept any other cheques cause it is not possible for us to cash foreign checks without having to pay substantial fees to the bank. Registered users will be shipped a disk with the latest release version of DeliTracker. By cooperating with this concept you help to ensure continued development of this product. Please send your registration card (Orderform) and the money to: Frank Riffel Merkstr. 27 8129 Wessobrunn Germany You may send bug reports, remarks, and suggestions to this address as well. If you have written a new soundsystem and you wish to adapt your replay-routine to DeliTracker, contact us. We will help you. DeliTracker may be distributed on public-domain, shareware disks, and electronic networks such as the Internet as longs as the followings conditions are fulfilled: ° all files must be kept together. You can find a list of all files in 'Distribution'. ° no part of the distribution may be changed in any way. The only exception is archiving (e.g. with LhA), but the original files must be 100% restoreable. ° The price of a disk that contains DeliTracker must be less than US $6 or 8.- DM. The same is the maximum price that networks may charge from their users for downloading DeliTracker. ° For use in commercial products the permission of the authors is required. DeliTracker was developed and tested very carefully. Nevertheless the Authors are not responsible for any damages that are caused by DeliTracker. Use at your own risk. 3.INTRODUCTION 3.1 What is DeliTracker ? DeliTracker is a soundplayer which supports several soundformats; some are SoundTracker 15 inst., SoundTracker 31 inst., NoiseTracker, ProTracker, StarTrekker without AM sounds and CustomPlay. Since these types are so common, their replay routines are built within DeliTracker itself. Additional players are loaded from disk, meaning that you can very easily add/update players by placing them into the DeliPlayers directory. DeliTracker is NOT a Songeditor, MIDIsequencer or Digitizer. It is only meant to play music modules in a comfortable way. 3.2 Why use DeliTracker ? There are many reasons for using DeliTracker; here is only a small list: ° system friendly and multitasks happily ° allocates the soundchannels ° correct playspeed in PAL/NTSC (uses timerinterrupts) ° works well with serial.device ° supports xpkmaster.library for decrunching ° supports up to 64 players ° runs fine with 680x0 and Kick2.0 ° ARexx support ° has a configfile ° enforcer and mungwall proof ° supports full CLI or Workbench (ToolTypes) environment ° easy to use & looks good ° has Volume/Balance sliders ° resident cli startup ° supports multiselect ° written in 100% Assembler 4. GETTING STARTED 4.1 System requirements DeliTracker doesn't need extensive hardware or software. An Amiga with Kickstart 1.2 or higher, 100KB free memory (plus memory for the module) and the 'req.library' are only required. If you want to use packed modules, the 'xpkmaster.library' and the corresponding sublibraries must be installed. Make sure that you use V2 of XPK! V1 is NOT sufficient. For DeliTracker_2.x, Kickstart and Workbench 2.04 are required. Of course your System should be equiped with a Monitor that has speakers or even better with a HiFi system. 4.2 Starting from CLI/Shell Open a Shell or CLI window and CD to the directory where DeliTracker is located. Now you can type 'DeliTracker' followed by none/one/more options explained in 5.4. The options and arguments should be separated by spaces. DeliTracker automatically detatches from the CLI and you may close the CLI window. If a wrong arument is supplied DeliTracker quits with a short helptext. Example: 'DeliTracker config DT.config volume 32 filter 0' Starts DeliTracker with 'DT.config' as configuration file, turns the lowpass filter off (not on A1000's) and sets the volume to 32. 4.3 Starting from Workbench Open the drawer that contains DeliTracker and start it with a double click. All options can be set as ToolTypes by using the 'Info' item from the Workbench. The options must be separated by an '=' from the arguments. Invalid Tooltypes are ignored. DeliTracker can be used as a 'Default Tool' for automatic playing of modules. Example: Config=DT.config PrefWinXY=0/11 Volume=43 Window=NO ; CX_Popup=NO for 2.x version If DeliTracker is started with these tooltypes, it loads 'DT.config' as the configuration file and sets the volume to 43. The main window is not opened in case arexx is running. This assures that the user can quit DeliTracker. The next time the preferences window is opened at 0/11. 4.4 Installation If you already use an older version of DeliTracker, please delete all files of the old distribution and your configuration files before you install this version. Copy the version for your kickstart in a directory of your choosing. Now copy the whole 'DeliPlayers' directory into this place. We strongly suggest that you move never or seldom used players from DeliPlayers/ to DeliPlayers/PlayerStore/. If you don't do this you waste memory! When DeliTracker is started every player in the 'DeliPlayers' drawer will be loaded. Note: any loaded player will stay in memory until the user unloads it or DeliTracker is exited. DeliTracker need req.library to run. If you don't have req.library in LIBS:, double click on the CopyLibs icon. The script will install V2.5 of req.library in LIBS:. 5. BASICS 5.1 Player With DeliTracker it is possible to load single players. This has the advantage that you may only load the players that you need (= efficient memoryusage). Of course, you may unload any player at any time. Another drawback is that you only need to know the 'DeliTracker-player' rather than every single player. Multimedia applications in conjunction with ARexx greatly benefit from this (e.g. You may play any Module in an AmigaVision(TM) presentation). Another major advantage is that the player interface is very flexible so everyone may easily enhance/update/adapt or write players. DeliTracker has the most common players built in. These are: StarTrekker without AM sounds, SoundTracker15, SoundTracker31, NosieTracker and Protracker. There is another player called 'CustomPlay'; this is a special player that was created to play special modules that contain their own player. These 'modules' may NOT be crunched, because they are loaded via LoadSeg() to allow relocation. All external players are listed in the 'Players.doc'. For details on programming players read the includefile and 'Programming.doc'. 5.2 Packed modules If xpkmaster.library V2 or higher is installed DeliTracker will use the library for decrunching. Certain players do NOT support module packing! This is due to the fact that those players load the module by themselves rather than using the internal LoadFile() function. If the player-info field for a particular player shows 'Packable....NO' you are not allowed to crunch modules of this player. NOTE: Don't pack custommodules because they are loaded and RELOCATED via LoadSeg()! 5.3 Kickstart 2.0 To use some of the features provided by Kickstart 2.0 we have decided to build a special version. The current version does not use all features of V37, but all 2.0 specific handling is done right. DeliTracker_2.x has the following advantages/differences to the Kick 1.3 Version: ° Menulayout done with gadtools.library ° Colors changed to match the 2.0 palette. ° The mainwindow has a Zip-Gadget ° Modules can be played by simply dropping the moduleicon into the mainwindow (Appwindow). ° complete PubScreen support ° usage of Systemrequesters ° hotkey for MainWindow opening/closing; some things may be controlled with the Commodities Exchange Program 5.4 Options To allow an easy and flexible configuration, DeliTracker uses the following options. These options are used as KEYWORDS in Tooltypes, Configurationfiles and CLI templates. The options are not case sensitive! Option Default value and description -------------------- ----------------------------- cx_priority <pri> 0 (default priority) Sets the commodities priority. Valid values are -128 to 127. This option is only found in the 2.x version of DeliTracker. cx_popup <yes|no> (2.x) yes (window opened) or Defines if the control window should be opened window <yes|no> (1.3) at startup. If it is set to 'no', the main window will not be opened. It may be opened via hotkey, Commodities Exchange (2.x) or with an ARexx command. The Kick 1.3 version only supresses the opening of the mainwindow if the AREXX-Server is running. cx_popkey <string> "" (no hotkey) This defines the hotkey that is used to open or close the main window. If the mainwindow is closed via hotkey the prefs window is closed as well -- the same applies to Hide Interface. To disable the hotkey use the INACTIVE option of the Commodities Exchange Program. This function is only accessible in the 2.x version. config <file> "ENV:DeliTracker.config" Loads the specified file as a configuration file. Note: This option may not be specified in a configuration file! module <file> No file, empty module list. Adds the <file> to the module list. pubscreen <Screen> "", default PubScreen (usually Workbench). Let you specify the name of the public screen where DeliTracker should pop up. If the given screen is not available (e.g. does not exist), DeliTracker opens its windows on the default public screen. This function is not implemented in the Kick 1.3 version. Note: Screen names are case sensitive! playerpath <path> "DeliPlayers" Sets the path where DeliTracker loads the external players. windowxy<XPos>/<YPos> 0/0 Attempts to open the mainwindow at the given position. If this fails the window will be opened at 0/0. prefwinxy<XPos>/<YPos> 0/1 Attempts to open the prefs window at the given position. If this fails the window will be opened at 0/1. volume <volume> 64 (maximal volume) Sets the volume to <volume>. Where volume can range from 0 to 64. balance <balance> 0 Sets the balance to <balance>. Where balance can range from -64 (left channels only) to 64 (right channels only). reqlines <lines> 0 (requester internal default setting). Specifies the filerequester height in lines. subsong <number> 0 (first subsong) Sets the subsong counter to <number> if the player for the first module in the soundlist supports subsongs. playing <yes|no> yes (first module is playing) Defines if the first module in the soundlist should be loaded, when DeliTracker is started. filter <yes|no> no (filter off) Switches the internal lowpass filter on or off. An advantage of having the filter off is that frequencies over 7kHz are not cut off. This has the effect that most modules will sound much better. Note: On A1000 this switch has no effect. quick <yes|no> yes (module is played immediately after loading) Defines if a loaded module should begin to play immediately after loading or if the module is in a paused state. This option is meant for synchronization purposes in ARexx scripts. random <yes|no> no (sequential order) Lets you specify whether a Next/Prev-Song event should take a randomly picked or the following (preceeding) list entry for loading. Once a module has been played it won't be reselected until other selected modules have been played. This behaviour is also known as 'Shuffleplay'. This option only works if there are more than 2 entries in the modulelist. append <yes|no> no (replace modulelist with new selection) Lets you specify whether the soundlist should be appended at the end or replaced by the current selection. If this option is set, multiselect of modules from different directories is possible. fadeout <yes|no> no (don't fade) Lets you specify whether the song should be faded out on a eject event or if no smooth transition should be done. This feature is only available for players that support volume changing. songend <yes|no> no (ignore songend signals) Lets you specify whether songend events should be ignored or not. SOME players support a notification of the song end. If this option is set, DeliTracker will pause the module and load the next module in the list. If only one module is in the soundlist then it is paused after the song has played once. timeout <secs> 0 (no timeout) Lets you specify the amount of time (in secs) after that DeliTracker will cause a Next-Song event. A value of 0 disables timeout. 5.5 Configuration files A Configuration file contains one or more options with the appropriate arguments. The only option that is not possible is the 'config' option. Only one option per line is allowed. DeliTracker can create configfiles with the save functions from the prefs window. Another way is to create a config file by your own with an editor or automatically by using the following NewList alias: 'alias ModList NL -hTigfsF "module=\'%P\'" []'. Only redirect the output to a file. Example of a configfile: windowxy=473/15 random=yes songend=yes timeout=300 reqlines=50 subsong=2 playerpath="Data:DeliPlayers" module="Data:Modules/SonicArranger/MF__Slowmotion1.3.pp" module="Data:Modules/FutureComposer13/hidden part.pp" Tooltypes and CLI options have a higher priority over the options in a configfile. This means they can override config file settings. At startup DeliTracker tries to open 'ENV:DeliTracker.config' as the default configfile. If this file can be opened, DeliTracker uses all settings that are contained therein. After this DeliTracker loads the external players and plays the first module. If the Configfile is not present, DeliTracker tries to load all external players that are located in the 'Deliplayers' directory on the current path. 6. HOW TO CONTROL DELITRACKER 6.1 The main window The main window is the central part of the DeliTracker. All module specific things may be controlled with this panel. 6.1.1 Gadgets This is a overview of the functions of the gadgets. If a gadget is drawn ghosted then this option is not accessible for this player. Two reasons why this is so: First, the soundsystem does not have this feature at all (e.g. SoundTracker has no SubSongs), or second, the player is not perfectly adapted (which is more likely). +---------+-+------------------------------------------------+-+ | | | [] | | [15] [1] | ? + +------------------------------------------------+ + | | | [] | | [14] +---+-----+-+--+-----+-----+-----+----+-----+-----+-----+----+-+ [2] | + | | | | | | | | | | |¯¯\ | +---+ |< | < | << | |> | >> | > | >| | [] | ^ | | | | [3] | - | | | | | | | | | - | +--+ | +---+-----+----+-----+-----+-----+----+-----+-----+-----+------+ [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [1] opens or closes the Prefs-Window [2] Faster: plays song a little faster [3] Slower: plays song a little slower [4] Prev Song: play the previous song. This gadget is only enabled if more than one file was selected. If Randomplay is selected this button picks a random module. See also Randomplay. [5] Prev Pattern: Jumps to the previous pattern. If the current pattern is the first, the counter is set to the last pattern. [6] Prev SubSong: Jumps to the previous sub-song (if available). [7] Play/Pause: Plays a paused sound or pauses a playing sound. [8] Forward: Jumps to the next pattern in the module. If the current pattern is the last, the counter is set to the first pattern. [9] Next Song: This button loads the next module form the selected Soundlist. If the last module of the list is playing and you press this button the first module of the list will be played (cyclic list). If Randomplay is selected this button has the same function as the Prev Song button. [10] Next SubSong: Plays the next SubSong of a module. This function allows you to select other melodies in the module. Not every Soundsystem provides you this feature. One of the most common Soundsystems that provide multi-modules is TFMX. [11] Stop Song: This button resets the patterncounter and the speed to the initial default value. [12] Kill Song: stops the actual module and removes it from memory. [13] Load Song: Opens the filerequester and lets you select one or more modules for playing. The first selected module is loaded and played. If enough memory is available, DeliTracker will use double buffering. This means that the actual song continues playing until the next song is loaded. [14] Balance Control: Let you change the Volume. [15] Volume Control: Let you change the Balance 6.1.2 Menus Project Load Module <A> L .........Open the filerequester. Play/Pause .........Play or pause a module. Stop Playing .........Stopt the actual module. Eject Module .........Stop playing and remove the actual module from memory. ================= Prefs ... .........Open prefs window ================= About ... <A> ? .........Open 'About' requester. ================= Quit <A> Q .........Quit DeliTracker. Control Faster .........Increase Playspeed. Slower .........Decrease Playspeed. Forward .........Jump one Pattern forward. Backward .........Jump one Pattern back. Next SubSong .........Play next Subsong. Prev Subsong .........Play previous Subsong. Next Module .........Load the next module in the Soundlist. See also Randomplay. Prev Module .........Load previous module. 6.1.3 Shortcuts All functions of the mainwindow can although be reached with shortcuts. To make them easy to remember we decided to order them hirarchically on the nummeric keypad. In additon you may specify a HotKey for opening and closing of the mainwindow (refer to cx_hotkey). * and <A> L open the filerequester for moduleselection. / open or close the prefs window. ] and ) play next song in the modulelist (only if more files are selected). [ and ( play previous song (same as above). 8 play next subsong. 7 play previous subsong. 5 step to next pattern. 6 skip one pattern back. + increase playspeed. - decrese playspeed. 1 stop song (stop playing, reset patterncunter). 0 play/pause (toggles between playing and paused). . stop song and remove it from memory (eject). 9 decreases the volume (besides -). 6 increases the volume (besides +). 2 changes the balance (decreases the volume of the right channels). 3 changes the balance. (increases the volume of the right channels) <A> ? opens the 'About' requester. <A> Q quits DeliTracker. 6.2 The preferences window The preferences window is for seting all global and player specific options. To open the prefs window you may either select the 'Prefs ...' menu or the '?'-Gadget of the mainwindow. Of course, there is a short cut ('/') and an arexx-command ('openprefswin'), too. To activate a player select it from the player requester. After selecting a player, all informations about the player is shown beside it in the player information field. 6.2.1 Gadgets ADD Load an external player and set the playerpath. If a player with the same name is already loaded, the player with the lower version number will be expunged. DEL Deletes the selected player. This means the player is unloaded. Internal players may be deleted too, but the memory is not freed. Filter Refer to 5.4 filter option. Quick Refer to 5.4 quick option. Random Refer to 5.4 random option. Songend Refer to 5.4 songend option. Append Refer to 5.4 append option. Fadeout Refer to 5.4 fadeout option. Time Refer to 5.4 timeout option. Load Config Load a saved configuration and set all values. Save Config Save all actual settings and the current module list to a configuration file. Save List Only save the module list to a configuration file. Config If the player provides a player specific configuration routine this routine will be called. OK Close the preferences window. You can set the playerdirectory by typing the path into the stringgad (on the lefthand of the ADD gadget) or using the filerequester (ADD). 6.2.2 Shortcuts To make the shortcuts easy to remember we decided to use the first letter of the function (if not already used) as shortcuts. Shortcuts may be entered either in lower or upper case. a <A>dd (Filerequester for loading players). d <D>el (delete selected player). l <L>oad (Load a config file). s <S>ave (Save a config file). c <C>onfig (configure selected player). o <O>k (Close preference window). q <Q>uick (toggle quick). f <F>ilter (toggle filter). r <R>andom (toggle random). p A<P>pend (toggle append). e Song<E>nd (toggle songend detection). u Fadeo<U>t (toggle fadeout). t <T>ime(out) (activate timeout gadget). 6.3 ARexx Nearly every function of DeliTracker may be controlled with ARexx. This is very nice if you are using other ARexx aware software like AmigaVision(TM). DeliTracker is addressed as a function host with the name "rexx_DT". DeliTracker provides the following commands: quit Leave DeliTracker. filter <yes|no> yes: Switch filter on. no: Switch filter off. quickstart <yes|no> yes: Turn quick on. no: Turn quick off. random <yes|no> yes: Turn Randomplay on. no: Turn Randomplay off. songend <yes|no> yes: Recognize songend signals. no: Ignore songend events. append <yes|no> yes: Activate append mode. no: Deactivate Append mode. fadeout <yes|no> yes: Activate fadeout mode. no: Deactivate fadeout mode. timeout <SECS> Set timeout to given number of seconds (SECS) If SECS = 0 the timeout function is disabled. volume <VOL> Set volume to <VOL> (Range VOL: 0 to 64). balance <BAL> Set balance to <BAL>, 0 is default, -64 left only, 64 right only (Range BAL: -64 to 64). forward Play next pattern. backward Play previous pattern. nextsong Play next song (module). prevsong Play previous song (module). nextsubsong Play next subsong. prevsubsong Play previous subsong. faster Increase playspeed. slower Decrease playspeed. loadconfig [FILE] Load configfile [FILE] if [FILE] was specified, else pop filerequester up. saveconfig [FILE] Save configfile [FILE] if [FILE] was specified, else pop filerequester up. savelist [FILE] Save module list to [FILE] if [FILE] was specified, else pop filerequester up. loadplayer [PLAYER] Load the [PLAYER] if specified, else open loadplayer requester. deleteplayer <NUMBER> Remove player number <NUMBER> from memory. Note: all modules of this player won't be recognized any longer. configplayer <NUMBER> Call the configuration routine of the player <NUMBER>. playpause Play/Pause song. stop Stop song. playmod [MODULE] play [MODULE] if [MODULE] was specified else pop requester up. eject Remove active module from memory. pubscreen <SCREEN> Closes all DeliTracker windows and tries to open the mainwindow on the pubscreen <SCREEN>. This function only exists in the 2.0 version. openmainwin Open and/or activate mainwindow. closemainwin Close mainwindow. openprefswin Open and/or activate prefs window. closeprefswin Close the prefs window. status <group> <dependent> Returns the actual status. This funtion is divided into three different groups: global settings (g), player specific settings (p) and module dependent settings (m). Additional arguments are specified after the group. <group> = g : Global <dependent> = <cmd> <cmd> description returnvalue ver DeliTracker version number dir playerdir string num players number led filter <yes|no> qst quickstart <yes|no> rnd random <yes|no> app append <yes|no> fad fadeout <yes|no> end songend <yes|no> tim timeout in seconds number mwi mainwindow closed/open <yes|no> pwi prefswindow closed/open <yes|no> vol current volume number bal current balance number ply paused or playing <yes|no> pub prefered pubscreen string <group> = m : Module <dependent> = <cmd> <cmd> description returnvalue dir moduledir string fil filename string pnr actual PlayerNr number max selected modules number num actual position in list number <group> = p : Player <dependent> = <playernum> <cmd> <cmd> description returnvalue nam name string cre creator string ver player version number vol volume <yes|no> bal balance <yes|no> jmp patternjump <yes|no> spd playspeed <yes|no> sub subsong <yes|no> cfg config <yes|no> pck packable <yes|no> Square brackets [...] mark arguments that may be omitted. Arguments in angle brackets <...> must be supplied. Note: For almost any command example scripts are available. All commands may be entered in lower and upper case. 7. TROUBLESHOOTING Preferences window can't be opened: Check the screen height. It must be at least 190 Pixels + Barheight. The Barheigth depends on the screenfont height. Try to use a smaller font (topaz 8). Some external players have trouble with >68010 or SuperHires; these problems often can't be fixed. The cause of this lies in the coding style (e.g. the player is part of the module and contains modulespecific code/data) of these players. Many players are hitting at the basic principles of programming on the Amiga. Such things as poking directly into processor vectors or working with nullpointers are often seen. Don't be astonished if enforcer hits occur. These hits are only from external players and *not* from DeliTracker itself!! Usually the playspeed of the players are the same on PAL/NTSC machines, because a CIA, rather than a VBlank IRQ is used. Since some players essentially need a VBlank interrupt, these players have different playspeeds depending on the selected video mode (PAL/NTSC/Productivity). Some players dont take notice of the VBR (on >68000) and write directly to the interrupt vector table ($70 Vector/Audio-DMA-End). This may have the effect that you won't hear anything when VBR is nonzero. Those players are marked in the player documentation. For Modem users: All players that use the DeliTracker internal timer Interrupt should now work well with serial transfers. Players that generate their own timer interrupt will probably not(!). This is due to the fact that instead of executing the actual playroutine in the timer interrupt itself, we cause a SoftInt (so that the real routine executes in a lower interrupt priority than the RFB interrupt). 8. THE FUTURE OF DELITRACKER The future of DeliTracker is leading to 2.0 (or higher;-)! This is the last release that features a Kick 1.3 version. New external players will stay compatible unless they don't ask for 2.0 or a higher DeliTracker version. At the moment we are thinking of writing a xmusic.library. This library will essentially be the same as DeliTracker and easily allow you to integrate Sound into your own programs. 9. ACKNOWLEDGEMENTS Our special thanks go to the following people: Our betatesters Stefan, Daniel, Börnie and Manfred for their bugreports and ideas. Armin Sander (Oktalyzer) and Carsten Schlote (Sonic Arranger) for creating DeliPlayers for their soundsystems. All on IRC #amiga (Internet Relay Chat) Markus Illenseer and Christian Rattei for the correction of the german docs. Kevin Dackiw for the enhancement of the NoisePacker players and the correction of the english doc files. [Hope it is a little clearer...8-) -- KD] U. Dominik Müller for XPK. Colin Fox and Bruce Dawson for the incredibile req.library. Eric Kennedy for TstApp.rexx. and all others, who have send replays, modules or registrations.