How to Use the Blue Ram Basic "PLAY%( ) Command ----------------------------------------------- A Tutorial By George Moses (Arcadian, June 1983, Page 128 and August 1983, Page 156) Note: This document has minor revisions and corrections by Richard Degler and Adam Trionfo. The PLAY command can be directly related to machine language programming and the music synthesizer. This article makes a perfect companion to the "Nutting Manual's" Music Processor section (pages 56-60) and Bally Arcade's audio information (103-105). - October 28, 2011 We understand that the first thing most new owners of Blue Ram Extended BASIC do is read their manual and then call Perkins Engineering and exclaim "What in the heck is the "PLAY" command anyway?" I can tell you that I was one of those people myself. What follows is an expose (in simple terms) on how to use the PLAY command to play music, make neat sound effects, and at the same time do graphics, scrolling and animation with neither operation affecting the other. The PLAY command is used to initiate a sound string beginning at a specified address. The format is as follows: PLAY%(!8000) Or PLAY%(26375) or PLAY%(100) as three good examples. As long as the address immediately following PLAY is the first address of the musical score in memory. Let's learn how to set up a musical score. It's very similar to the format that was presented in the three voice bally BASIC music tutorial that ran in the Arcadian last year except that with the PLAY command the duration goes first, followed by 3 voice inputs. The following score can most easily be input using Perkins' new Blue Ram Utility (only $5.00) which allows you to type it in just as it is, then play it. Here is a sample score in hex: MUSIC SCORE HEX CODE Comments: 80 31 Set Master Oscillator To 31H. B0 66 06 Set Ports 22 21 Volumes To 6. 90 FC Set 3 Voice Per Entry Format. 0F 2C 32 47 Duration 0FH plus 3 Voices. 0F 32 47 2C 0F 47 2C 32 0F 2C 32 47 0F 32 2C 47 0F 2C 32 47 0F 35 2C 43 0F 2C 43 35 0F 43 35 2C 0F 35 2C 43 0F 2C 35 43 0F 35 2C 43 F0 You'll notice all durations in this score happen to be "15" or (0F hex). With durations counted in 60ths of a second, we are therefore using chords which last 15/60 or 1/4 second. When you play this sound string you'll hear it in staccato, a process where the Music Processor gives you 1/60th second of silence between chords. If you wish to change that to a slur where one chord blends into the next, you must insert the "slur indicator" which is an E0 (hex). Put the E0 anywhere in the score. At the beginning, or just before or after any completed command or chord, (never in the middle!), and the Music Processor will toggle itself to the opposite state. Notice that the last entry in the scope is "F0". This is the command to end the sound string. It quiets the Music Processor and stops all background operation. If you have the Blue Ram Utility you may input the score I gave you byte for byte just as you see them. If you don't have the utility, (poor deprived programmer), then you will need the following short program to help you. This works in Blue Ram BASIC only. > 5 CLEAR ;NB=16 >10 NT=0;A=!607F >20 PRINT #l," %(",A,")=",;INPUT""B >22 IF B=100PLAY%(!607F);GOTO 20 >23 %(A)=B >30 A=A+1;%(A)=!F0 (To stop the sound.) >40 GOTO 20 When you run this program you may type the music score in byte for byte as shown here, but you must precede each hex number with an exclamation point so the computer doesn't take it as a decimal number. Each number must also be followed by a carriage return (GO). An example of input follows: !90 !FC !80 !31 !B0 !66 !06 And so on. If at any time you wish to hear the score up to your last input just type the number 100 (GO) and it will play. Then you may continue inputting where you left off. Or you can halt the program and type PLAY%(!607F) since !607F is the beginning address of the score with this routine. Your score can be as long as memory permits. You can play it from within your BASIC program using the PLAY%(! ) command and it will play in background mode while your regular BASIC program continues to operate normally. As I promised, this introduction to the PLAY command was kept as simple as possible. It is recommended that you put in a few scores and practice with sheet music or make weird sound effects for your games. Very shortly this tutorial will be followed by another one which will explore the many Music Processor commands which exist in your On-Board ROM which will allow you to jump (conditionally or unconditionally) from one score to another, commands to allow repeats of specified portions of your score, how to change the input format from the 3-voice input shown here to 1-Voice, 2- Voices, Noise, Vibrato, Calls and Returns. In closing, let me give you 4 addresses in your On-Board ROM that contain scores in the Gunfight game. The addresses are: PLAY%(!1F9F) Home On The Range PLAY%(!1FAD) Taps PLAY%(!1FBD) Funeral March PLAY%(!1FD7) Gunshot Sound These addresses are for the newer set of ROMs. If they don't work with your Arcade try adding 5 to each address. Music Processor Commands, Part II --------------------------------- In the June '83 issue of Arcadian (page 128) we described the procedures to use the Blue Ram BASIC "PLAY" command. This article will continue where we left off. Here we'll describe every command built into your Music Processor. The format we will follow will be the "op code" in hex, followed by a description of what that command does. The Commands: 00 thru 7F A number in this range is taken as a control byte which specifies duration in sixtieths of a second. The duration byte is followed by the data to play. (See June article, page 128) 80H thru 87H The value of the next byte will be loaded into the port number described by the lower 3 bits of the above number plus 10H. Example of this: 80... the next byte will load port 10H or 16 decimal, the Master Oscillator. So, 8023 sets the MO to 23H. 81 will be followed by a value to load port 11H. And so on all the way to 87H to load port 17H (Noise). 88H thru 8FH The next 8 bytes will load ports 17H, 16H, 15H, 14H, 13H, 12H, 11H and 10H respectively and you'll have to load them all (even with zeroes) because the music processor will be expecting all 8 bytes of data to store. 90H The next byte is the string format identifier, telling the computer which ports're going to be loaded in this string format. The format will be one duration byte, followed by the bytes to load each port expected by the processor according to the format you selected. 7 6 5 4 3 2 1 0 +-----+-----+-----+-----+-----+-----+-----+-----+ | |&(17)| |&(18)| |&(19)|&(20)|&(23)| +-----+-----+-----+-----+-----+-----+-----+-----+ Fig. 1 The number of bytes that will follow the duration byte is equal to the number of bits set in positions 0, 1, 3, 5, and 7 of the String Format Identifier. Example: 90H ;Next byte is String Format Ident. C0H ;In binary C0 is 1100 0000. Expect one byte defining Tone A after each ;Duration Byte. 0FH ;Duration Byte of 15/60ths of a sec. 19H ;Load Voice A (Port 11H) with a freq. of 19H 0FH ;Duration of 15/60th of a second. 30H ;Voice A=30H And so on, until you change the format of the string. A1H thru AFH (PUSH Number onto music stack) Are the commands to repeat a sound string. This will push a number on the Music Stack equal to the lower 4 bits plus one. Example: 91H=1001 0001 in binary. You can see the low 4 bits equals 1. If the number pushed on the stack equals the lower 4 bits plus one, that number will be one plus one., or two. If you wish the string to be played twice, begin the string with the 91h and end the string with a C0H. When the C0 is encountered the number on the Stack will be decremented by one and the program branches to the address specified by the next two bytes. That address should be the beginning of the string to be repeated. After playing the string two times and decrementing the number stored on the stack to zero, the program will skip the 2-byte address following the C0 and go on to the next piece of data stored. So the repeat command, 91H thru AFH will push the numbers 2 thru 16 on the stack. Just select the one you want and place it at the beginning of your string! [Note: This originally was published as "91H thru AFH." 9xH does slip through here, but it should be A1H - AFH according to the DNA Manual's "PUSHN macro NUMB; DB $A0 + ((NUMB-1) AND $0F); endm" define.] B0H The next two bytes control volume in ports 16H and 15H respectively. B0 77 07 sets the volume port 16H to 77H and port 15H to 07, setting the volumes of all 3 voices to 7. (Port 16H controls vol. A with the lower nibble and vol. B with the upper nibble.) C3H (Music JumP) Jump to address specified by next 2 bytes C3 00 80 ;Jump to address 8000H and ;continue playing data from there [Actually, C1 and C2 work for MusJumP just as well.] CAH (Music CAll) Call address specified by next two bytes and push return address on the stack. [Standard CALL is $CD naturally, but C4 thru CF (except C9) all do MusCAll.] D0 THRU DFH Call Relative (plus lower 4 bits), push the return address. Example follows: D8 ;Call current program counter address +8 and push return address ;on the stack C0H Decrement counter that you pushed on stack with the 91H thru AFH command, then jump to the address specified by the next two bytes if counter is non- zero. Skip next 2 bytes, pop counter if it is zero. C9 Pop address stored on stack. Return to that address and continue from there. E0 Reverse slur indicator. When this command is encountered it allows notes to slur from one chord to the next with no silence in between. If the slur indicator is "on" and the E0 hex command comes up again the slur will turn "off" and you will have a staccato effect. In this state each chord will be "clipped" by 1/60th of a second of silence before the beginning of the next chord. E1 Silence for a duration stored in next byte. (00 thru 7FH). Then continue music. [Any of E1-EF and/or F1-FF fall into this.] F0 All sound off. Zero all sound ports. Abandon reading any further data. End of string Well, I hope this answers a few questions about the Music Processor. Now some of you may become great sound effects programmers like Scot Norris, who did almost all of the audio work on the cartridges you have in your Bally Arcade slots. Happy noise making! George Moses P.O. Box 686 Brighton, MI 48116