Otherware

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

/ Otherware / Otherware_1_SB_Development.iso / amiga / misc / amigalib.lha / edplayer.lha / edplayer / EdPlayer1.0.DOC < prev next >

Wrap

Text File | 1991-08-01 | 46KB | 844 lines

============================================================================ EdPlayer version 1.0 by Ed Mackey ============================================================================ Hello, and welcome to EdPlayer!! First, distribution: EdPlayer is shareware. You can distribute it by any means, including BBSs, PD disks, and FTP services like AB20, etc. You can also distribute EdPlayer with your own programs, as long as you include a note that EdPlayer is freely distributable, and do not make any copyright claims on EdPlayer. If you want to distribute EdPlayer with a commercial package, please contact me first (address at end of document). I would LIKE for you to keep this document with EdPlayer whenever possible, because many important things are explained here (like EdPlayer's ARexx interface) that aren't explained anywhere else. However, if you MUST distribute EdPlayer without this file, you may. Also, note that if you distribute the kd_freq.library, you MUST keep its DOC file with it. This is explained later in this file, in the "Buttons" section under "OPEN", the only button that uses the kd_freq.library. EdPlayer is copyright 1991 Ed Mackey. ---------------------------------------------------------------------------- BUT, what IS it?? EdPlayer is a music player. It can play both NoiseTracker modules and MED version 3.10 (or greater??) modules. Note that SOME MED 3.00 modules will work also, however, others will show up as "Unknown or corrupt module" because MED 3.00 had a serious bug in the module-saving routines (it didn't word-align the chunks sometimes, and caused other MED players to GURU, but EdPlayer has a check for this and will only report a "corrupt module" error). To fix a MED 3.00 or earlier module, simply load it into MED 3.10 and save it back out as a MODULE. As far as NoiseTracker modules go, I have an early version of the NoiseTracker player (the same one I used in my game MegaBall. The source code said "Mahoney & Kaktus, Hallonsoft" and is freely distributable to the best of my knowledge). What EdPlayer can be used for: I had MANY uses in mind as I was designing EdPlayer. I wanted a music player that could be used directly for entertainment, or multitask while the user did word-processing or whatever, and also be able to run from both ARexx and CLI scripts for use in IFF slide shows, presentations with background music (AmigaVision, DVideo III, Director 2, etc.), music for games written in AmigaBasic or other languages for which there are no music-playing routines available, and basically any situation at all where someone wants their Amiga to play some tunes. ;-> ---------------------------------------------------------------------------- Starting EdPlayer: There are four ways to start EdPlayer... ---> (1) Workbench Icon. Brings up some CD-player like controls. (2) CLI: "run EdPlayer" Also brings up the CD controls. (3) CLI: "run EdPlayer -i" Brings up a tiny "iconified" WB window. (4) CLI: "run EdPlayer -h" NO user interface, ARexx port ONLY! Note that I recommend using the "runback" command rather than "run" if you have it, so that the CLI window itself can close before EdPlayer does. NOTE: A simmilar effect can be achieved with "run <NIL: >NIL: EdPlayer". Note that ALL 4 startup methods open the EDPLAYER message port, which can accept instructions from AREXX (if you have it) as well as the "telled" command explained below. ---------------------------------------------------------------------------- OK, now that you know how to run it, you can start playing with it even before you finish reading these DOCs. This is because there is an ONLINE HELP FUNCTION that is self-explanatory. However, this function includes a lot of scrolling text, and so when you get tired of reading that, you can come back here because ALL OF THE ONLINE HELP IS ALSO AVAILABLE HERE IN THE DOCs. Plus, some features, like the AREXX port, are ONLY described here in the DOCs!! ============================================================================ A N D N O W , T H E B U T T O N S : ============================================================================ If you're reading this, I hope you have tried playing with EdPlayer a bit. You know that there are a lot of buttons on the main panel that appears when you run the program. Here they are, left-to-right, slowly working downward from the top. (There are no keyboard equivalents for any of these buttons in this release. You'll have to use your mouse. Sorry). POWER: This exits EdPlayer rather immediately. No "Are you Sure?" prompts or anything, because they sometimes annoy me. Of course, all the proper shutdown routines are run, such as unloading the current song, etc. Note that the close gadget in the "iconified" WB window has this same function (see ICONIFY below). (ARexx/telled users: see KILL, SELF in ARexx section) "T": Tempo control. NoiseTracker modules can have different tempos depending on whether you are in PAL or NTSC mode. This button toggles between the two tempos, with the current status appearing in the LED display. Note that this option is memorized "per song" in program mode (see PRG below). (ARexx/telled users: see PALM, NORM, NTSC in ARexx section) HELP: This is the "Online Help Function." I call it "online" because you can get help while you are using EdPlayer. (Of couse, this being an Amiga, you can multitask and get help from the DOCs while you are using EdPlayer too. Oh, never mind.) Anyway, you click here to turn help on, then click on the buttons you want help with, and then click here again to turn help back off. "|<": EJECTs current song, moves to previous program selection, and displays title of that selection. You can use this to flip through a program, select where you want to start, and press PLAY to start. (see PRG below). (ARexx/telled users: see PREV in ARexx section) ">|": Same as "|<" above, but moves to NEXT prg selection rather than the previous one. (ARexx/telled users: see NEXT in ARexx section) PRG: OK, now it's time to explain programs. A "program" is a list of module filenames that EdPlayer can memorize, along with two options per name (PAL / NTSC and FADE / NO FADE). When such a list exists, EdPlayer will attempt at the end of each song to load and play the next song in the program, using the options for that song. The two buttons listed above this one scroll through the program. Sorry, but in this version there is no "Random play" function. If someone really wants it, just let me know! Now about the PRG button itself: Be careful with this button!! It's main use is for ERASING the current program! This is because CREATING programs is more easily done with the OPEN button described below. If EdPlayer has a program in memory, the "PRG" LED will light up on the display. (ARexx/telled users: see JUKE, LOAD in ARexx section) EJECT "^": Unloads current song, freeing lots of CHIP memory. Does NOT erase current program. (ARexx/telled users: see EJEC in ARexx section) OPEN: For this one, you NEED the kd_freq.library version 2.0 or higher in your LIBS: directory! This library might have come with the EdPlayer archive, because its copyright notice is as follows: >>If you want to use 'kd_freq.library' in any freely distributable program, >>you may include the 'kd_freq.library' file as long as you also include the >>'FR_User.DOC' file and mention 'Copyright 1990 Khalid Aldoseri'. Oh yes, the author of this library, Khalid Aldoseri, can be reached at the following address: Khalid Aldoseri P.O. Box 505 Manama, Bahrain. Fax: (973) 694777 Compuserve 75166,2531 And I almost forgot to mention that this library is Copyright 1990 Khalid Aldoseri. Now that you have the kd_freq.library, you can use the EdPlayer OPEN button to bring up it's file requester. With this requestor, you should select the filename of a module you want to hear. If there is no program, the song will load and begin to play. However, if there IS a program (even an empty one created with PRG), the song's name will be added to the program. NOTE THAT A MUCH EASIER way to make programs is with the file requester's "Extended Select" feature. To use this, hold down the SHIFT key and click several module filenames. As you click them, they light up, and when you press "OK", ALL of the filenames will be added, in alphabetical order, to the END of the current program. If no program exists when you use this feature, one will automatically be created. To start any program, press PLAY. (ARexx/telled users: see LOAD, PLAY, JUKE in ARexx section) PLAY "|>": This button has many functions. If no song is loaded, it will try to get a module name from the program and load & play it. If a song IS loaded, but not playing, it will ignore the program and play the current song. If a song is ALREADY playing, this button will PAUSE it (either immediately or fade-to-pause, see FADE). Finally, if a song is paused, and you press this, the song will continue, either immediately or fade-back-in (see FADE again). (ARexx/telled users: see PLAY, PAUS, CONT in ARexx section) STOP: This button has a square on it. It stops the music IMMEDIATELY, regardless of the state of the "fade" light. If you want a fade-out, fade to a PAUSE and then press STOP. I made it this way because I found that in practice, when people press STOP, they just want the music to STOP right there because they're debugging or something, and fading is mostly for song changes in a program. NOTE that you can NOT continue after a STOP! You must start again from the beginning of that song. If you wanted to continue, you should have pressed PAUSE (a function of the PLAY button above). (ARexx/telled users: see STOP, FADE in ARexx section) LOOP: This button has a little curved arrow on it, signifying a loop. It will toggle on and off the similar-looking LOOP LED on the display. When this LED is lit, the current song will loop to the beginning (or wherever the composer decided it would loop to) and keep playing. In program mode, each song will come to an end, but the whole program will loop when it runs out of titles. When this LED is NOT lit, the current song will end (either immediately or fade-to-stop, see FADE) and in program mode, the program will end when it runs out of titles (but it won't be erased). Note that certain MED modules have a special "STOP" command ($FFE) encoded into the end of the song, and these modules will NEVER LOOP, regardless of this button. (ARexx/telled users: see LOOP, AUTO in ARexx section) FADE: This button has a triangle that is supposed to signify volume fading away (sort of). Whenever you use PAUSE or CONTINUE, or when the song reaches an end just before a program change, the song can either stop/start immediately, or gradually fade out/in. This button toggles on and off the similar-looking FADE LED on the display. When this LED is lit, EdPlayer will try to fade the song as mentioned. When this LED is dark, EdPlayer will just do instant stops and starts. If a song comes to an end, and LOOP is off (or program is on) and FADE is on, the song will LOOP anyway, but begin fading to a stop, and the program change will occour after the fade. Note that this button has NO effect on (1) the STOP button or (2) MED modules that have the special STOP effect ($FFE) encoded into them. However, these MED modules WILL trigger program changes, of course. SETTING the fade rate: see the "PAUS" command in the ARexx section!! (ARexx/telled users: see PAUS, LOOP, AUTO, FADE in ARexx section) FILTER: This button looks like a dot with little waves coming out of it. It has a similar-looking FILTER LED on the display panel that shows the status of the Amiga's audio filter, which is also displayed by your Amiga's so-called "power" LED. I have no clue why the Amiga's power LED does this. If anyone knows please tell me. Anyway, this button turns it on and off, however, this is THE most useless feature in all of EdPlayer, because the filter is also automatically handled by the music playing routines. (ARexx/telled users: You can't blink the filter! Ha, ha!! You'll just have to live without this oh-so-useful function.) ICONIFY: This button looks like a WB 1.3 back gadget, but it's NOT the one in the title bar. It gets rid of the CD-player like controls, saving a bit of CHIP mem, and produces a tiny "iconified" window on the WB screen. This window has only two options: The close gadget will exit EdPlayer (see Power above), and the right mouse button, if pressed when the window is selected, will bring back the CD-player look. Of course, all the EdPlayer functions remain in effect in this mode, like program changes and ARexx messages. Plus, this mode saves a bunch of CPU time, because EdPlayer can sleep rather than updating the display every video cycle. If you REALLY need to conserve memory, you should hide EdPlayer altogether and then close the WB screen, using one of the ARexx commands and then some utility for closing WB: (ARexx/telled users: see MENU, ICON, HIDE in ARexx section) DISPLAY: This button looks like two calculator 8's. It toggles between four display modes, described in the Display section below. MIDI: This button is supposed to look like a MIDI plug. Sort of. Anyway, it toggles MIDI on and off. The MIDI LED on the display shows the current status of MIDI. When the light is off, your serial port is free for things like downloading, etc., and when the light is on, the serial port is allocated for MED modules to send MIDI data with. Note to midi.library users!!!! See "MIDL" in ARexx section! (ARexx/telled users: see MIDI, MIDL, NOMI in ARexx section) VOLUME SLIDE: Well, what do YOU think it does? It controls the volume of a piece of music. Also, it might NOT be such a good idea to fuss around with this thing while the music is already trying to FADE in/out of its own accord due to the FADE LED. (ARexx/telled users: see VOLU in ARexx section) INFO BAR: You can click in the space between EdPlayer's "feet" to display the name and author info of the current song. Also, this space shows other useful stuff like the online help, and the version info when you first start EdPlayer or when you come out of an Iconify or HIDE. NOTE TO MODULE AUTHORS: If you want to create some "author info" to appear in this bar whenever your module plays, there are 2 ways: (1) For NT-MODs: Create some instrument names preceded by a "#". Each instrument name in the NT-MOD that starts with a # will be linked together (add your own spaces!) and displayed in the bar. (2) For MED MODs: Create an "annotext" as the MED documentation describes. SPECIAL EFFECTS: EdPlayer can handle some neat effects in the author info of a module (NT OR MED). These effects all start with a <`> mark, NOT to be confused with the more ordinary <'> mark. PLEASE NOTICE the difference between ` and ' !!!! The ` key, on my American keyboard, is in the top-left, just under the ESC key. Here are the effects: (lowercase letters only!) `s = SLOW. Text will scroll at 1/4 normal speed. `n = NORMAL. Text resumes normal scroll speed. `f = FAST. Text goes THREE TIMES normal speed!! `r = RED. Text from here on will be red. `y = YELLOW `g = GREEN `t = TAN (EdPlayer's tanish color used on buttons) `p = ICKY, ICKY PURPLE!! `w = WHITE, the default. `` = ` (if you really want a ` mark to appear). To use any of these effects, just insert them in the author text of your module. Note that using a ` mark at all will FORCE the text to scroll, even if it was short enough to fit all on the lo-res screen at once (NOT LIKELEY!!). ============================================================================ L E D D I S P L A Y ============================================================================ Ah, such a complicated, confusing display. Not really! It's pretty simple when you break it down. OK, I'm going to start in the BOTTOM-LEFT, and go RIGHT. You'd better be looking at the display while you're reading this (I'm looking at it while I write it)! First, in the bottom-left, you see the PRG LED. It's probably dark, so look very closely. It only lights up if you have a "program" active (see PRG in the button section above). Next, to the right of PRG, is a little bent arrow. This is the LOOP LED (see LOOP in the button section). To the right of that is the FADE LED which, by default, is lit up when EdPlayer starts (see FADE in the button section above). Then there is the FILTER LED (again, see FILTER above). Then there are two LEDs that say "PAL" and "NTSC". When EdPlayer starts, whichever mode you are in should be lit up. You can change this for tempo correction of NoiseTracker modules, but they BOTH go dark for MED modules which need no such correction. To change it, see "T" (Tempo) in... you guessed it... the button section, above. ---------------------------------------------------------------------------- AND NOW, THE LEDs which are *NOT* explained in the button section, above. YEAH!! To the right of PAL/NTSC you see something like a four-bar equalizer. As the Amiga has four built-in voices, it shouldn't be too hard to figure out what this does. Fun to watch when playing a song! To the right of that, you see a few LEDs (we're now as far right as we can go)! The "NT-MOD" will light up when EdPlayer has a NoiseTracker module loaded, and "MED 3.10" will light up when there is a MED module loaded. "PAUSE" will light up when in pause mode, and will BLINK when EdPlayer is FADEing to a pause. The "MIDI" light is special: The whole MIDI thing lights up when MIDI (direct or midi.library) is active, BUT, when a song is playing, the five red dots (representing MIDI prongs on the end of a MIDI cable) will go dark again, and BLINK as MIDI messages are passed out of EdPlayer! I think this is a neat effect during MIDI songs. ---------------------------------------------------------------------------- And finally, the digits. These digits are controlled by the "Display" button (which looks like two calculator 8's) and have FOUR MODES. MODE 1: Below the digits you see TRACK, POS, and TOTAL. When a song is loaded, it's current position will be displayed above "POS", with the total number of positions being displayed above "TOTAL." Above "TRACK" you may see a program number, if this song is part of a program. SPECIAL CASE: If you are in a program, but no song is currently loaded, the "POS" will disappear, allowing "TRACK" and "TOTAL" to work together, displaying the current and total number of songs in the program, respectively. MODE 2: In this mode, you see LINE, POS, and PATT below the digits. The "Pos" light is exactly the same as in mode 1, displaying the song's position. The "LINE" shows a much more exact position inside the POS itself, and "PATT" shows the current pattern number being displayed. This mode is for people who like to follow the progress of their songs through the player, and also for people like myself who just want to see all the busy, changing numbers going on. MODE 3: This mode just displays your Amiga's system time. You can distinguish this mode by the "AM" or "PM" that lights up. To set the time, just use the AmigaDOS "Date" command, or some other utility. Actually, if you have a battery-backed-up clock in your Amiga, the time should already be set from your startup-sequence via the "SetClock Load" command. Why am I explaining this?! Go read your Amiga's manual if you're confused! MODE 4: This mode just displays the system date, in MONTH, DAY, YEAR format. You can distinguish this mode from the others because NO funny LEDs like "Track" or "AM" or even ":" or "/" come on. To set the date, see MODE 3 above. Well that about wraps it up for the LED display. Oh yes, if EdPlayer tries to display a number greater than 99, two dashes "--" should appear instead. Also, the two dashes appear above "TRACK" when there is a program, but no selection in the program is "current". Pressing PLAY at this point will move the current selection to 01 if necessary before loading & playing. Note that there is NO LIMIT on the number of songs in a program!! NOT 99, NOT 65536, OR ANYTHING LIKE THAT! This is because I used Amiga exec's wonderful doubly-linked lists to handle the list of names. SO, you can keep adding names to a program until your whole Amiga's memory is full of nothing but filenames, and you may not have enough memory left to actually load a song, but you will NEVER get a "Too many names in Program" error. Well, actually, if the memory allocation for the filename storage fails, you can get an out-of-memory error from EdPlayer, but if you're THAT close to being out of memory, you're probably headed for a GURU real soon! Anyway, just thinking about typing all those millions of filenames makes my fingers hurt! ============================================================================ A R E X X / T E L L E D S E C T I O N ============================================================================ EdPlayer has a special message port. This port is more than an ARexx port, because it can accept both ARexx messages and special "EdPlayer" messages in the same port. The reason for this is that some unfortuneate people still don't have ARexx! What are you guys waiting for?? Anyway, included in this archive are two programs and their respective source codes, called "Telled" (Telled.asm) and "cteled" (cteled.c). The two are almost identical: Telled was written in Assembly, being as SMALL as possible, for easy use in script files. Cteled was written in Aztec C, and is somewhat larger because it actually returns error messages on the screen. Both of these programs transmit the special "EdPlayer" messages so that ARexx is not required. Their source codes are provided in case you want to write your own programs that transmit these messages. However, it is STRONGLY RECOMMENDED that you look up in your ARexx manual the proper way of sending true ARexx messages, so that you know how to send messages to other ARexx applications, not just EdPlayer. For those of you making script files: If you have ARexx, you'll almost certainly want to make ARexx scripts instead of CLI scripts. For that, use an "address 'EDPLAYER'" type command. Again, see your ARexx manual for more details (Are they giving out ARexx manuals with new WB 2.0? I sure hope so! Will someone with WB 2.0 please tell me how much ARexx documentation came with it?) ANYWAY, for you people without ARexx, you're stuck making CLI scripts! For this, use "telled" or "cteled" as described here: NOTE!: the parameters are different. Telled does NOT use quotes, while cteled DOES: CORRECT: >>>> telled PLAY mod.cream of the earth ;Note that telled NEVER needs any quotes no matter how many spaces are ;in the line. >>>> cteled "PLAY mod.cream of the earth" ;Note that cteled NEEDS quotes, and all parameters go in the SAME ;set of quotes, because EdPlayer will parse it, NOT cteled. ;In the above two examples, note that the example command "PLAY" is ;UPPER CASE! This is VERY IMPORTANT, because EdPlayer will return ;syntax errors for lower- or mixed-case commands. INCORRECT: telled "PLAY mod.test module" ;telled NEVER needs quotes X X cteled "PLAY" "mod.test module" ;put ALL in one set of quotes X X telled play mod.test module ;commands (PLAY) must be in CAPS! XXXX Well, I hope you can get the hang of that. There should be some example scripts in the archive, for more examples of sending commands. ---------------------------------------------------------------------------- Now it's time for a complete list of commands. Note that you may give ANY of these commands to EdPlayer by (1) using the CLI to issue "telled" or "cteled" as shown above, or (2) send the commands via ARexx to the ARexx port "EDPLAYER" (all caps). I'll list the commands in the order they were created. Note that each one is FOUR LETTERS in ALL CAPS. Any needed parameters should follow the command separated from it by ONE SPACE. Parameters in [<brackets>] are optional. Parameters in <these things> are required! LOAD <filename> This command is used to load a module into EdPlayer. EdPlayer automatically figures out what module type it is, but does not yet start to play it. This command can NOT be used with programs! It erases the current program. If you want to use programs, see JUKE below. Anyway, LOAD will wait until the module finishes loading before it returns, so it can report if there was an error or not. Note: ALWAYS use a FULL PATH with LOAD, because the current directory of EdPlayer may not match the current directory of the program sending the command. PLAY [<filename>] This command can be used with or without the parameter. If it is given with no parameter, it will attempt to play the current song. If there is a parameter, it will call LOAD first, and then PLAY. This command will wait for the module to load, so it can report errors like LOAD does, but it will return once the song begins to play. Note: This is NOT the same as the PLAY button on the CD, because there is no PAUSE feature here, and neither is there auto-loading from the current program. For these features, see PAUS, CONT, and NEXT. STOP Stops the music immediately, just like the STOP button. EJEC EJECts the current song, un-loading it from your CHIP mem. (Just like the EJECT button!) VOLU <volume> Sets the music's volume, and affects the volume slide on the CD player panel. <volume> can be an integer from 0 to 64. see FADE PAUS [<rate>] This will pause the music. If there is no parameter, the music will pause immediately. If there is a <rate>, then the music will fade to a pause. Common <rate>s are: 1 = Very slow, 2 = slow, 4 = initial default fade rate from CD panel, 8 = medium fast, 16 = fast. Integers from 1 to 32 usually work OK. NOTE: Entering a new PAUSE rate may not affect the end-of-song fade-out rate, BUT, it WILL set a new default for the panel's rate for everything. So next time someone uses the panel to fade something, it will happen in the last-used <rate>. This side-effect on the panel goes for ALL EdPlayer commands that use <rate>, such as CONT, AUTO, FADE, etc. It is, in fact, the ONLY way to set the panel's fade rate! Maybe in future versions there could be a slider or something so that the rate can be set from the panel itself?.... see CONT. CONT [<rate>] This will make the music continue, if it has been PAUSed. If no <rate> is given, the rate from the last PAUS will be used. For a description of <rate>s, see PAUS. FADE [<rate>] This is for fading the song to a STOP. You cannot continue after this!! The <rate> works like in PAUS, except that if it is not specified, it defaults to 4, taking the panel's rate to 4 along with it, probably. (Yet another feature that needs testing!) AUTO [<rate>] This command is for automatically getting a song (or program) to stop at the end (this is the default when EdPlayer starts). If no <rate> is specified, the song will stop immediately when it reaches the end, otherwise, the song will loop and start to fade to a stop at the specified <rate>. During programs, it will set the fade-out rate at the end of each song, as well as telling the program not to loop. If you set this rate but still want your program to loop, just issue a LOOP command afterwards. For a descripton of <rate>s, see PAUS. LOOP The current song or program will loop and keep playing, instead of stopping, when it reaches the end. This is the opposite of AUTO. KILL This has the same effect as pressing the "Power" button: The current song STOPs, gets EJECted, the program is erased, and then EdPlayer exits the system, all very quickly. It's a good idea to ask the user if he/she wants this before you send a KILL command. JUMP <position> This is an interesting command. It tells EdPlayer that on the next position change (a position currently shows up as "POS" on the CD panel), the music should jump to the specified position rather than just proceeding to the next one. My brother created a perfect example of what this can be used for: He wrote a module (in MED) that had several sections, each section ending in a $B command for looping. Then he turned EdPlayer's LOOP on, and in a DeluxeVideoIII presentation, had EdPlayer start playing this song. Of course, it got caught in the first looping section. But then, as the presentation continued (it was more like a game actually), he sent JUMP commands to EdPlayer to play the different sections. As the user moved from one part to the next, the music changed to match the current place in the game. It was a really neat effect. Anyway, if this DVideo game ever becomes playable, I'm sure he'll distribute it.... SELF [<rate>] This command works exactly like AUTO, except that at the end of the song's fade-out, EdPlayer KILLs itself (exits the system). I don't think I ever updated this command for use with programs, because quite frankly I never found a use for it myself. If you use it, and want it updated, tell me! (SELF stands for SELF-destruct) (Updating would mean having it wait for the end of a program, rather than the end of a song, before the self-destruct.) NORM This command is for controlling the tempo correction on NoiseTracker modules. It sets it back to NORMal, with no correction. see NTSC, PALM NTSC This command is like NORM, but if EdPlayer thinks your machine is running in PAL Mode, it will try to make NT modules sound like they are being played at NTSC tempo. If you execute NTSC on an NTSC machine, EdPlayer should automatically call NORM instead. see NORM, PALM PALM (PALM = PAL Mode) This command is the opposite of NTSC: If you have an NTSC machine, EdPlayer will try to make the modules sound like they are being played at PAL tempo. If you call PALM on a PAL machine, EdPlayer should do a NORM instead. see NORM, NTSC MENU This command will bring up EdPlayer's CD-like control panel if it's not visible, and redraw it if it is. The EdPlayer version information will be re-displayed. see ICON, HIDE ICON This command will close the CD display and create the iconified WB window that also appears when someone presses the "ICONIFY" button or starts EdPlayer with the -i option. Selecting this WB window and pressing the right mouse button will bring back the CD panel. see MENU, HIDE HIDE This command will remove EdPlayer's user interface altogether, as if you had started EdPlayer with the -h option. This allows WB to be closed if necessary, but is not really recommended because the user has no way to undo this using the mouse alone. It can only be undone with the MENU or ICON commands, above. see MENU, ICON MIDI This is for direct MIDI on MED modules. If any midi.library resources have been allocated, they are deallocated and the library is closed. Then, EdPlayer tries to allocate the serial port for direct MIDI output, using the default MED MIDI routines. This is the mode that the MIDI button on the panel uses. Safe to call even when a module is playing, because a playing MED module will be paused VERY briefly during the allocation & init of the MIDI stuff. see NOMI, MIDL NOMI NO MIdi. Deallocates any and all MIDI-related resources, such as the midi.library or serial port. Safe to call even when a module is playing. see MIDI, MIDL MIDL [<midi_destination>] MIDi.Library. If you own the midi.library by Bill Barton, you can use this command to take over MED's MIDI output: Instead of allocating and directly controlling the serial port, EdPlayer will attempt to open the midi.library and create a "midi source" called EDPLAYER. Then, if there is a parameter, EdPlayer will try to make a "Midi Route" from its source to a destination of the name specified in the parameter. This means that if you do NOT give a parameter, you must create your own route with a Patch Bay before anything can happen. The "standard" use of this command would be "MIDL MidiOut" because MidiOut is the standard midi.library output to the serial port. However, there are more useful options if you are multitasking with other applications that use midi.library, and want to recieve MIDI data from EdPlayer. For instance, if you had a MIDI monitor called "MidiMon", you could send Edplayer a "MIDL MidiMon" to monitor EdPlayer's MIDI output. Like the other MIDI commands, it is safe to call MIDL even when a module is playing, and MIDL works differently based on what resources are already allocated. For instance, if the serial port is allocated when you call MIDL, it will be dumped so that midi.library can open. Also, if midi.library was ALREADY open, MIDL won't close or re-open it or the EDPLAYER midi_source. It will, however, erase the old midi route and make a new one, because routes can become useless if their destination disappears. NOTE that MIDL is CASE-SENSITIVE! Use MidiOut, not MIDIout etc. see MIDI, NOMI PREV EJECts current song, moves to previous song in program, and tries to load AND PLAY it. PREV waits for the load to complete before returning, so it can result in all the usual load errors (file not found, out of mem, etc.) as well as the "no program" error. Note that the PREV "|<" button on the panel does not work exactly like this, because it does not automatically try to load and play. see NEXT, JUKE NEXT Exactly like PREV, but moves to NEXT program selection instead of previous one. This command is typically used to start a program once it's programmed in. see PREV, JUKE JUKE <filename> This is the way to make EdPlayer programs from an ARexx or CLI (telled) script. Each call to JUKE adds the one <filename> parameter to the end of the current program. It's a good idea to include the full path in this filename, because EdPlayer's current directory may not be the same one that the script file with the JUKEs is executing from. Once a program is created (by a series of "JUKE"s), the program can be started by a call to "NEXT". Note that calling PLAY will NOT start a program unless the first module is already loaded, because the command PLAY does not work exactly like the button PLAY. So, you should start the program with NEXT. see PREV, NEXT ============================================================================ E R R O R C O D E S ============================================================================ When EdPlayer gets an error, usually from an ARexx or telled command, it reports that error to the calling program. If you use "telled", you will not see an error message in your CLI window, although errors with numbers 10 or higher may cause your script to abort. If you use "cteled", a full error description should appear in your CLI window. And finally, if you use an ARexx script, the error number will appear in the script's window (the script may halt for errors >= 10), but no discription will appear. In ALL these cases, however, if the CD panel is open when the error occurs, an error number and description will appear in it. This is useful for debugging things like DVideoIII presentations which do not even return the error number from a failed ARexx message. If for some reason you CAN get an error number, but you would like a much fuller description, here are the codes: 0 = No error. 6 = No program! PREV or NEXT was called, but there is no program there to get the next songname from. 7 = Illegal JUMP. Someone tried to use the JUMP command to jump to a pattern that wasn't in the song, and the command had to be ignored. 8 = Can't continue. CONT was called, but the song was STOPped, and could not continue. 9 = Nothing to PLAY! Someone issued a PLAY with no filename and no song currently loaded. If you were expecting it to pull a filename from the program in this case, you're wrong. Use NEXT! 10 = Syntax error. The first four letters of the message did not make a valid command. Perhaps they were lower-case, or maybe there were quotes in "telled" parameters. Or maybe it was just garbage... 11 = MIDI not available. If the MIDI command returns this, then your serial port is probably not free. If the MIDL command returns this, then maybe you don't have midi.library in your LIBS: directory or something. 12 = File not found. A very common error. Check spelling & path! You must use a FULL PATH with EdPlayer, because EdPlayer's current directory may not match the controlling program's current dir! ALSO: If you have two disks, both named "Empty" or both named "ST-00" or something, EdPlayer can't tell them apart! You will end up seeing this error a lot. RENAME your disks. Make them UNIQUE! And, save yourself a headache: Write the volume name of a disk ON ITS LABEL, so that when EdPlayer asks for it, you know which one it's asking for. 14 = Disk error. Maybe the file is corrupt, or there was a read/write error or something. 15 = Out of memory. There is not enough CHIP RAM to load the module. I know that MegaBall 2.0 can load songs into FAST ram, but that is ONLY because there are five songs, and the group of them go into FAST together and get buffered into CHIP one song at a time. This method will obviously not work with EdPlayer which only loads one song at a time anyway. So we're stuck with CHIP RAM again. :-( 16 = Unknown module type, or corrupt module. Perhaps you are trying to play a MED 3.00 module with the MED 3.0 bug in it, or perhaps you are trying to play an earlier format of MED modules, or even a song or something instead of a module. If the error happened because of a MED mutant, just load it into MED *3.10!* and save as a MODULE. This should fix it. If the tempo goes nuts, know that the MED author changed the tempo commands and it's not my fault. ;-) 21 = If EdPlayer returns this, then it is exiting (shutting down). However, this error is much more often generated by telled itself when it cannot find EdPlayer in the system. For instance, if you have a script file that starts EdPlayer, and immediately tries to send commands to it, without waiting for it to load and get ready (open it's port, etc.), then your script will probably die with this error code. You should wait for EdPlayer to start, and the best way to do this is with the "waitport" CLI command that comes (I think) with ARexx. Example: After starting EdPlayer, and before sending commands, have the CLI execute "waitport EDPLAYER". ============================================================================ W H E W ! ! ! ! ============================================================================ For those of you that read all the way through that, congratulations are in order. I personally really hate programs who's DOC files are as big or bigger than the program itself, and so I'm not too happy about the fact that despite all my efforts to make this thing user-friendly, I still wound up with MonsterDOCs. Oh well. "The moving cursor writes, and having writ, GURUs." Oops. No, wait, that's not how it goes. I know. "The moving fingers type, and having typed, forget to press 'Save'. THEN it GURUs." Hmm, that's not right either. Oh darn. Never mind. ---------------------------------------------------------------------------- If you use EdPlayer, or ESPECIALLY if you would like to use EdPlayer but there's some little vital feature missing that's stopping you, then I WANT to hear from you!! For instance, if you have, say, an ASM source code that plays ST or NT mods much better than the player built into EdPlayer, send me a copy! I'll see if I can include it in the next release or not... (This is assuming you can legally send me this copy, and I can legally use it! If not, DON'T.) At this point I'm also going to suggest maybe possibly sending me a donation, if you like EdPlayer or want to see improved versions of it. I'm not going to expect everyone who sends me mail to give a donation, just the people who want to see EdPlayer improve, or have found it useful. Also, I'm not going to say what kind of donation. It can be money or software or whatever, as long as it's *NOT* (a) illegal/pirated software, (b) XXX graphics, or (c) drugs, alcohol, etc. :-( Also I'm open to comments & suggestions about almost every aspect of the program, with the possible exception of people who think that naming the "EdPlayer" after myself was an egotistical, stuck-up move. It's FREE software. And I'm not a creative naming genius, obviously. If you think YOU are, send your much-improved names, money, software, and/or comments to: US mail: Ed Mackey PO Box 475 Wayne, PA 19087 Or: Internet: ELM4@ns.cc.lehigh.edu BITNET: ELM4@LEHIGH.BITNET As you might have guessed from the network addresses, I'm a student at Lehigh University in Bethlehem, PA. I'm currently about to enter my Junior year at Lehigh, being a Computer Science major. This message was written on July 30, 1991. I may not be at Lehigh after '93, and I may even move my home address from Wayne, PA before then, so I didn't provide EITHER of those US mail addresses here. The only one I provided is the PO Box in Wayne (above), which I will keep EVEN if I move, so that address should be valid for years and years to come. About my brother, Al Mackey: He's a senior in High School. He and I work together on programs, usually splitting the workload as follows: All code - me. All music - Al. All graphics - first drawn by Al and then modified and rearranged by myself, making the gfx sort of a 50%/50% project. This is the way we did our game Ball, our game MegaBall (Fred Fish #477), and also this project (EdPlayer). I'm sorry I can't really distribute a bunch of Al's great music with this program, but I'm trying to keep the archive as small as I reasonably can. Of course, Al uploads a lot of his modules to local BBSs such as Somerton BBS (215-464-6775) where you can DL them. Also I sometimes upload a few to the AB20, for those of you with access to a Unix machine with commands like "ftp 128.155.23.64". These places are also good places to watch for future versions of EdPlayer, provided I get a good response to it. Let's try once more: "The moving finger presses the POWER button, and having pressed it, this document comes to an end&$#^#(*