F u n M u s i c ================ By BEWESOFT INTRODUCTION FunMusic is a program for simple and easy music-playing on ATARI XL/XE computer. It allows you to play a kind of music in real-time using a joystick, or a mouse from ATARI ST (strongly recommended). FunMusic doesn't require any knowledge of music-theory (only a bit of sense). All you need is a bit of patience and this manual. Beside of this main function, you can also compile the music to be used in your own programs. But FunMusic is NOT a real music-editor. If you are able to write good songs for example in MUSIC PROTRACKER 2.4 or CHAOS MUSIC COMPOSER, then you should do so - you'll get much better results. However, if you can't compose music with the "real" music-editors, FunMusic gives you a chance to create a kind of medium-quality music easily. FunMusic is Freeware - you can make copies, give them to your friends (recommended) etc., as long as no changes are done to the program. Note: If you're a musician, you'll probably find some insufficiencies in both the program and this manual. Since my knowledge of music-theory is rather weak, I had to set some things by experimenting, and I really don't know how to call these things in correct English. FunMusic was NOT written for advanced musicians. Beside of this, also my English isn't the best... WHAT'S ON THE SCREEN Now let's look at the main screen of FunMusic. The screen is divided into several windows. All functions are done by moving the cursor (the small flashing arrow) into a window and pressing the controller's button ("click"). In the upper part of your screen you can see a large grey window, that allows you to control the basic line of your music. Another four windows are below - each of these is connected to one of the four sound-generators of your computer. In these windows you'll set the instruments, the background melodies, and also the real-time playing will be done here. The main settings are at the left edge of the screen. These do affect several things - also in the other windows. MAIN SETTINGS The main settings are the small fields at the left edge of the screen. The first of them (at the top of the column) allows you to select number of the sound-channels you want to use. When you select a number less than 4, some of the sound-channel windows will disappear. The number of voices is of course limited, but you can select from more and better instruments. The second from the top is the basic tone of the whole music. Set it where you want... It's possible to match the range of used instruments better, by changing this setting. The third setting is the tempo (9 is the fastest). If you're recording a music to be compiled, it's recommended to set a slower tempo while playing in real-time (to get a better chance to click on the single tones exactly in the right time), and then change the tempo before the compilation. The next field is a small picture of a floppy-disk. If you click on this field, the main screen will disappear, and the FunMusic Compiler will begin its work. (Look at the "Compilation" part of this manual.) The last (and largest) field at the bottom of the left column shows the configuration of controllers. You can see two joysticks (or mouses), with a symbol of the I/O connector in the middle. You can connect a joystick or ATARI ST mouse into each of the connectors (the second controller is only used in the real-time playing mode, when you've selected it for some window). When you start the program, it's configured for two joysticks. If you're using mouse(s), just connect it and move a bit - the mouse should appear into the configuration automatically. But however, if you want to change the controllers, you must change the configuration yourself. To correct the config, just click on the controller-field. In the case that you can't move the cursor (because of a bad configuration), you can also change the config by pressing numbers "1" or "2" on the keyboard. It's also possible to control FunMusic from keyboard, but this is not very comfortable - it's good just for the first tries, when you've no controller handy at the moment. You should disconnect any controllers from the first port, and set it into the joystick mode. Now you can control the cursor with the keys with arrows (or the 1200XL F-keys), and click with the RETURN key. SOUND-CHANNEL WINDOWS Each sound-generator may be used for a background voice, or for the real-time played melody. To select the mode of a channel, just click on the small field at the left end of its window. You'll see a chip for a background voice, or a face with controller-number for a real-time melody. The setting is independent for each channel. The second field from left allows you to select the instrument. At the top of this small field there is a picture of a sine-wave, followed by a number and possibly a letter above the number. The number shows the selected waveform (poly-counter) - in other words the kind of sound (clean/noisy, hard/soft etc.). The letter above this number is the mode of sound-channel's clock. (No letter = 8-bit counter, "H" = 8-bit counter with 1.79MHz clock, "D" = 16-bit counter.) All you need to do is to click here, until you hear the sound you want. You must know that the scale of possible modes is affected by the other channels - only two instruments with "H" or "D" may be selected at a time, and each "D" require one channel to be removed. (So with 4 channels you can't select any "D", with 3 channels only one "D" is possible, and with 1 or 2 channels you can select from the full scale of instruments.) Below the waveform, there is the volume-indicator. It allows you to select the volume for the channel (in four steps). At the bottom of this small instrument-field, there is another selection - you can select the instrument-type ("bell" with a stroke, or "trumpet" with soft begin), and length of the sound (larger symbol = longer sound). At the top of the largest part of a Sound-channel window, you can see a line with some colorful bars. This line shows the scale of tones possible for the selected instrument. The green bar is for the best tones, blue is for a bit worse ones, and red tones are rather bad (not exact at the right, or too noisy at the left); the tones shown as a thin line (without of colorful bars) doesn't exist for that instrument. Below the line, there is another bar (yellow) - this is the scale for playing. You can move it by clicking, and so select how high the channels will play. The yellow bar may run into the thin line a little bit, but since this reduce the scale for playing, it's not recommended. For the real-time melody, you should select the green tones; for background voices also blue tones are mostly usable, if you've selected short instrument with low volume. (The red tones are just for the worst case, if you haven't too good ear for exact tuning.) On this indicator you'll see what are these "H" and "D" modes good for: "H" moves the possible scale to higher tones, and "D" gives a greatly wide scale of green tones. Below the scale-indicator bars - in the main part of a Sound-channel window - two different things may appear. When the channel is switched into the background-voice mode, you'll see the definition of background melody for that channel. Clicking on this field, you can place tones (you'll also hear them); to remove a tone, click on it again. A channel in the real-time melody mode shows a double horizontal line with green and blue bobs. When you click into this field, the real-time playing begins. The cursor(s) appear to these line(s), and you can move it only left or right. All the background voices begin to play - the currently played tones are highlighted. Also the upper Basic line window come into life, but about this I'll talk later. Clicking on the bobs, you can play tones of your melody. (The last played tone is indicated by a large yellow bob above the line.) The green bobs are good for long and significant tones, while the blue ones are just to run-over. At the begin of each background period, a tone is played even if you didn't click. If there are more real-time melodies, some bobs may disappear sometimes to prevent collisions between the melodies. To stop the real-time playing, you should move the cursor far away to left, and click somewhere in the Main settings area. Another way to exit from the real-time playing is to press the ESC key. BASIC LINE WINDOW The grey Basic line window looks like the sound-channel windows a bit. It does control changes of the scale for playing - just try it and you'll hear what I mean... Also this window may be switched to any of the two controllers, or into automatic mode, just like the sound-channel windows (the small field at the left end). In the automatic mode, you can define the line of your music in the same way as the background melodies (clicking in the main part of the window). After placing a point in the Basic line window, the background voices will play for a while (so you'll hear the effect of your selection - It'll play till the next click, or till the whole background-period is finished). When the Basic line window is switched to a controller, the real-time playing begins once you click here. (It'll also begin when you click on the empty field second from left - the Arrow-field - this is the way how to enter the real-time playing, when you've all channels in the background mode.) In the real-time playing mode, the Basic line window become empty (when it's switched to a controller of course), and you can select the background changes by moving your controller up/down. An arrow will appear into the second field from left, showing your command; at the begin of the next background-period, the scale will be changed (and the arrow will disappear). Your background-line will be recorded into the window, so you can later use (and edit) it in the automatic mode. COMPILATION The music played in the real-time mode is allways recorded into a memory-buffer (the capacity is 64 background-periods - that's two times over the Basic-line window - later the music isn't recorded anymore). When you like the music you've just played, you can compile it to be used in your own programs. Only whole blocks will be compiled (4 background-periods each - see the vertical lines in the Basic line window). Before the compilation, you can change the tempo. This is the only thing you can change at this point - other changes have no effect to the recorded music, and some changes even erase it (all changes that affect instruments, scales, and channel-modes). To compile your music, click to the picture of a floppy-disk at the left edge of the screen. Now the colorful main screen disappears, and a common blue text-page returns for a while. You've just entered the FunMusic Compiler. Now you must enter (from keyboard) the memory-address, where the music will work in your program (more about this later), and the filename (use the DELETE key for corrections). Then, the music will be stored into the specified file (in the form of a program-module), and the main screen of FunMusic returns. While editing the address and filename, you can hear your music - exactly the same as it'll be in your program. If you want to return to the main screen (the music isn't what you expected...), just press ESC. In the Compiler, there are also two special "hot-keys": CONTROL+X allows you to reset all settings to the default (the same effect as loading the FunMusic program again), and with CONTROL+Q you can leave FunMusic and return to DOS. Both the functions contain the well-known question "Are you sure?". MUSIC IN BASIC-PROGRAMS If you want to use the music for a program in AtariBasic or TurboBasic, you'll probably place the music-module to the upper part of memory. In the FunMusic Compiler, try to type the address $9000 ($B000 for TurboBasic), but don't press RETURN and look at the ending address shown beside. When it is lower than $A000 ($C000 for TurboBasic), everything is OK. In the case that it is not lower, try to change the address to $8000 ($A000), or even $7000 ($9000). Once the ending address is OK, remember the starting address, and continue with the compilation. (If you want to start your Basic-program again after pressing the RESET-key, without of re-loading of the music module from disk, then the ending address must be lower than $9C20 ($BC20 for TurboBasic).) In your Basic-program, you must first reserve a part of memory for the music-module. The reservation must be done again when you restart the program after RESET. It looks like this: POKE 106,x : GRAPHICS y You can select any graphics mode, but the "x" value depends on the address of the music module: $7000 -> 112 $8000 -> 128 $9000 -> 144 $A000 -> 160 $B000 -> 176 (The value must be allways a multiple of 16, otherwise you may encounter problems with displaying some graphics modes.) The next step is loading of the music module into memory. There are several ways how to do this. In the TurboBasic you should type: BLOAD "D:filename" In the AtariBasic there isn't any command like this. If you're using BW-DOS, or SpartaDOS, you can type: CLOSE #1:XIO 40,#1,4,128,"D:filename" Possibly it'll work also with MYDOS, but the correct syntax for this DOS is: CLOSE #1:XIO 39,#1,7,0,"D:filename" Another method is long and slow, but works with any DOS and both the Basic versions: 10 OPEN #1,4,0,"D:filename":GET #1,A:GET #1,B:IF A<255 OR B<255 THEN ? "ERROR":END 20 GET #1,A:GET #1,B:PLAY=A+256*B:GET #1,A:GET #1,B:C=A+256*B 30 FOR A=PLAY TO C:GET #1,B:POKE A,B:NEXT A:CLOSE #1 There are also other methods (fast and universal, with a subroutine in machine code), but the length of this manual is limited... When you've the music-module loaded in memory, you can use the commands: A=USR(address,1) ... Start the music A=USR(address,0) ... Stop the music The "address" is the same as you've used in the FunMusic Compiler. In TurboBasic, you can type for example "$A000" just like you did in the Compiler, but in AtariBasic you must use the decimal mode: $7000 = 28672 $8000 = 32768 $9000 = 36864 $A000 = 40960 $B000 = 45056 Note: The music may be started again (that is: from its begin) without of stopping it, and also stopping the music twice isn't error. When no parameter is after the address, the music will stop; any extra parametetrs will be simply ignored. For more advanced programmers: The music-module works only when the system VBI routine isn't disabled. It uses the VVBLKD vector ($224,5). The music-module works also together with other routines installed in that vector, but you can't change the address when the music is playing (stop it first). If you want to install VBI-routines with music playing, you must allways jump to the previous address (the music) at the end of your routine. In this case, the VBI-routine of music-module will not be removed when you stop the music, so don't overwrite the module! MUSIC IN ASSEMBLER The music-module is stored as a binary file. At the begin, there are a few things for you: PLAYER+0 ... The routine for BASIC PLAYER+3 ... Initialization PLAYER+6 ... VBI routine PLAYER+9 ... Volume (4 bytes) You need to call the initialization first (JSR PLAYER+3), with the parameter (1=Start 0=Stop) in the register A. The VBI routine should be called (JSR PLAYER+6) 50 times in a second. At the address PLAYER+9 you'll find the volume for all 4 channels (Read only!) - for the case that you want to create a kind of equalizer-graphics. An other way is to call the player in the same way as from Basic: MUSICON LDA #1 ;The parameter PHA LDA #0 ;High byte PHA LDA #1 ;Number of params. PHA JMP PLAYER In this case the player will install/remove its own VBI routine.