Sound Sensations!

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

/ Sound Sensations! / sound_sensations.iso / miscprog / pmusic11 / poly.doc < prev next >

Wrap

Text File | 1989-07-04 | 59.4 KB | 1,337 lines

Polyphonic Music Compiler 1.10 Polyphonic Music Player Copyright (c) 1989 GrigaSoft Productions _____________________________________________ / \ -*> FOR UPDATES FROM VERSION 1.00 SEE THE FILE: <*- -*> UPDATE.TXT <*- -*> ALL UPDATED MATERIAL THAT IS DOCUMENTED IN <*- -*> UPDATE.TXT IS MARKED '(UPDATED)' IN THIS <*- -*> MANUAL <*- \_____________________________________________/ IF YOU HAVE ANYTHING YOU'D LIKE TO SEE DONE WITH THIS PACKAGE (SPECIFIC SONG CODINGS, NEW APPLICATION IDEAS, ETC.) PLEASE CONTACT THE AUTHOR (EDWARD GRIGASSY, (512)385-1368) [call collect if you have to!]. For more personal info see section 7.5 of this maunal. INTRODUCTION ------------ Welcome to the world of polyphonic music! Recently several programmers working seperately have discovered and implemented the amazing ability to play three (count 'em) independent voices on the cheap IBM PC/AT/Clone speaker. Why is this amazing? Well, for years any IBM "Music" program was laughed at by experts simply because all the software could do was drone out a simple (not to mention, dull) melody. Lately the techniques to play three notes at a time, allowing true chords and harmony, has been developed. This package exemplifies the continued refining of these techniques. CREDITS ------- Steve Muenter: wrote the original assembly algorithm for playing three notes at once, Ted Holden: informed me of this algorithm and his program VMUSIC inspired all my work TABLE OF CONTENTS ----------------- Subject Section ------- ------- What's included ......................................... 1.0 What is Polyphonic Music? ............................... 2.0 MakePoly Compiler ....................................... 3.0 Explanation .......................................... 3.1 Use .................................................. 3.2 Requirements ...................................... 3.21 Starting MakePoly / Command Line .................. 3.22 Text File Format / Syntax ......................... 3.23 PlayPoly Player ......................................... 4.0 Explanation .......................................... 4.1 Use .................................................. 4.2 Requirements ...................................... 4.21 Starting PlayPoly / Command Line .................. 4.22 Other Polyphonic Music Programs ......................... 5.0 AutoHarp ............................................. 5.1 LoopPoly ............................................. 5.2 SoundEff ............................................. 5.3 TimeCHK .............................................. 5.4 Using the Polyphonic C library .......................... 6.0 The Library Routines ................................. 6.1 Using the Polyphonic Music Library ................... 6.2 How to use the Library Routines ...................... 6.3 Author's Note ........................................... 7.0 Program Development .................................. 7.1 Program Features ..................................... 7.2 Program Info ......................................... 7.3 Future Enhancements .................................. 7.4 Author's Corner ...................................... 7.5 1.0 WHAT'S INCLUDED --------------- Included in this current version of Polyphonic Music are the following files: MAKEPOLY.EXE -- The textfile to polyfile compiler PLAYPOLY.EXE -- The polyfile player LOOPPOLY.EXE -- The polyfile player which repeats until a key is pressed AUTOHARP.EXE -- The executable version of an example of how to use the Polyphonic Music C interface. SOUNDEFF.EXE -- A sound effect program which uses the Poyphonic Music C interface. TIMECHK.EXE -- The executable version of an example of how to use the processor speed-checking functions of the Polyphonic Music library. AUTOHARP.C -- The source code of AUTOHARP.EXE. SOUNDEFF.C -- The source code of SOUNDEFF.EXE. TIMECHK.C -- The source code of TIMECHK.EXE. POLYCOMP.BAT -- An example compilation batch file for a C program calling the Polyphonic Music functions POLY.H -- The header file for the Polyphonic Music C library POLYCHRD.H -- The header file for defining the array constants of lots of chords POLY.LIB -- The Polyphonic Music C interface library. NPOLY_S.OBJ -- The UPDATED C extended function poly() (small memory model) NTRIT_S.OBJ -- The UPDATEED C extended function tritone() (small memory model) POLYFUNC.OBJ -- The other C functions in the Polyphonic Music library SIMPTEST.PLY -- A polyfile song that is probably the first three- voice song ever heard on an IBM (see 7.1 - PROGRAM DEVELOPEMENT) TRIPTEST.SNG -- An example song file that displays use of simulated triplets POLY.DOC -- The documentation file you are reading *.SNG, *.PLY -- Various song files to play 2.0 WHAT IS POLYPHONIC MUSIC? ------------------------- The Polyphonic Music programs are an innovative system for allowing three voice music to be played on the IBM PC and compatibles. The package provides several uses of Polyphonic Music for the user. These are: o A command line controlled jukebox, in which the user simply compiles (MakePoly.exe) and plays (PlayPoly.exe) his/her songs, o A batch file enhancer, which can play three part music while waiting for a keypress, and o A C programming language enhancer, which allows three voice music to be played within a C program until a keypress is detected. [See section 7.4 - Future Enhancements for uses soon to be implemmented!] The Polyphonic Music programs use two techniques to play music. The first is the ability to compile a text file with commands similar to the IBM BASIC PLAY statement into a ".ply" file format which can be directly played from the command line, batch files, or even from within your C programs themselves. The second technique is only usable within C programs. It involves defining the music to be played within the program (in array form). This second method may be preferrable if the song is short or if the programmer doesn't wish to access external files. 3.0 MAKEPOLY COMPILER ----------------- 3.1 EXPLANATION ----------- The MAKEPOLY.EXE file, when run, compiles text (ascii) files into files in a ".PLY" format which can then be directly read by other Polyphonic Music programs. This program is necessary to translate a file of ascii music commands into the raw frequencies that the computer can play. 3.2 USE --- 3.21 REQUIREMENTS ------------ The MAKEPOLY.EXE program will run in MS-DOS (and compatibles) 2.0 or later. It needs less than 80K of memory depending on the size of the text file being compiled (usually needs 15K to 64K). It can be run from either a floppy diskette or a hard disk. To work properly, a text file of music commands (see 3.23 - TEXT FILE FORMAT / SYNTAX) is required. (For more information on errors, see 3.24 - MAKEPOLY ERRORS.) 3.22 STARTING MAKEPOLY / COMMAND LINE -------------------------------- To run MakePoly, make sure you are in the directory where MAKEPOLY.EXE resides. Enter the following command at the DOS prompt: MAKEPOLY <file1> [<file2>] where: <file1> = the name of the text file which contains the Polyphonic Music commands (see 3.23 - TEXT FILE FORMAT / SYNTAX). This is the file to be compiled. <file2> = the name of the output ".ply" file which contains the raw music (frequencies, and durations) which can then be played by other Polyphonic Music routines, such as PLAYPOLY.EXE (this name is optional) Note: If no extension is given on <file1> and/or <file2>, MAKEPOLY assumes ".SNG" (song) for <file1>, and ".PLY" (poly or play) for <file2>. Also, if the <file2> parameter is not given, MAKEPOLY will attempt to add the ".PLY" extension to <file1>. Examples: to compile a file named "SIMPTEST.SNG": MAKEPOLY simptest to compile a file named "ODE" MAKEPOLY ode. ode.ply 3.23 TEXT FILE FORMAT / SYNTAX ------------------------- MAKEPOLY compiles a file in a special format. The file is made up of ascii text with certain ascii characters representing certain music commands. The commands can be in upper or lower case. The commands have been derived directly from recent versions of the IBM BASIC "PLAY" command (although a few new commands have been added). Here is a list of the commands that MAKEPOLY will compile: On -- Sets the octave of subsequent note output. Any integer n is allowed, but values between 0 and 6 are recommended. The value 3 is the octave containing middle C (the only C written without ledger lines in the Treble Clef). Octaves n < 3 are lower in pitch, while those with n > 3 are higher in pitch. Each octave contains the notes from C to B (ascending). (note: if not specified MAKEPOLY assumes 3) Example: O4 -> sets subsequent note output to the octave above middle C Ln -- Sets the default note length. The integer n can be one of the following: 1 -- representing a whole note 2 -- half note 4 -- quarter note 8 -- eigth note 16 -- sixteenth note 32 -- thirty-secondth note 64 -- sixty-fourth note (note: n can be other values between 1 and 64, see 7.2 - PROGRAM FEATURES (discussion on triplets) for details) The number n is the length any subsequent note which doesn't have an explicit length following it will be assigned. (This is useful when a piece comprises largely of one type of note length.) (note: if not specified MAKEPOLY assumes 4) Example: L4 -> sets default note length to quarter notes Tn -- (UPDATED) Changes the current tempo for all subsequent notes. See the file: UPDATE.TXT This command, as well as the K command, can be embedded in any voice. The tempo of all three voices is changed at the point the Tn command is found. >,< -- Raise current octave up, down. The command > raises the current octave set by the O command, while the command < lowers it. The current octave is raised or lowered by 1. Vn -- Set subsequent notes to be played by voice n. The integer n can ONLY have the values 1, 2, or 3. All the following notes will be programmed to play in voice n, until another Vn is found with a different value for n. (note: an error occurs when you attempt to play notes before setting which voice to play them on; no voice is assumed as default) Any combination of the three voices is allowed, including ommission of 1 or more of them. Example: V1 -> sets up voice 1 to play the subsequent notes K -- Check the keyboard for a keypress. This command will abort the playing of the song if a key has been pressed. The playing routine will only abort in the place where the K command is specified. This command can be in any place in the song and it causes the player to check if a key pressed, and abort if so, at that point in the song. Example: V1EEKEF -> check for a keypress after playing two 'E' notes (if no key pressed, play 'EF') *..* (UPDATED) Allow a user comment. All text in between two asterixes is ignored by the compiler. This is useful if the music scorer needs to mark a section of music or explain something about what he is scoring. Example: *voice1:* V1O3 AB -> The words "voice1:" are ignored (skipped over) by MAKEPOLY Notes are entered in the following manner: <N>[#,+,-][n][.[.[. etc.]]] where: <N> = the name of the note. This may be one of the following letters ONLY: A,B,C,D,E,F,G -- musical notes P,R -- rests (pauses, silences) [#,+,-] = optional note modifier. #,+ -- makes the note "sharp" - -- makes the note "flat" (note: B# (or B+) = C, E# (or E+) = F, and C- = B, F- = E) [n] = the optional note length. Can be of the possible values described under the L command. If n is not included, MAKEPOLY assumes the default note length set by the last L command. [.[.[. etc.]]] = the optional dots on the note. Each dot modifies the note's length by adding 1/2 of the current value. There is no limit to the number of dots modifying any given note. Examples: e -- play note 'e' f#4 -- play 'f sharp' for a quarter note length duration a+8. -- play a dotted 'a sharp' eighth note b- -- play 'b flat' for default duration specified by last L command 4.0 PLAYPOLY POLYPHONIC MUSIC PLAYER -------------------------------- 4.1 EXPLANATION ----------- The PLAYPOLY.EXE file, when run, plays a ".ply" file in polyphonic (three voice) sound. The ".ply" file is a special file format that cannot be adjusted or modified directly; it is only for use by the Polyphonic Music playing routines. 4.2 USE --- 4.21 REQUIREMENTS ------------ The PLAYPOLY.EXE program will run in MS-DOS (and compatibles) 2.0 or later. It needs less than 80K of memory depending on the size of the ".ply" file being played (usually 15K to 64K). It can be run from either a floppy diskette or a hard disk. To work properly a ".ply" file must be specified. This file must be in a specific machine-readable format. 4.22 STARTING PLAYPOLY / COMMAND LINE -------------------------------- To run PlayPoly, make sure you are in the directory where PLAYPOLY.EXE resides. Enter the following command at the DOS prompt: PLAYPOLY <file1> [tval,/c,/s] where: <file1> = the name of the ".ply" file which contains the Polyphonic Music in raw form. Such a file can only be created by the MakePoly compiler. This is the file to be played. One of the following optional 2nd parameters may be used: tval = the tempo you would like to set PlayPoly to play at. If not given, PLAYPOLY assumes 1024. This can be any positive number ranging up to 65535. The lower the number, the faster the tempo. Included in the Polyphonic Music package is a program called TIMECHK.EXE which will approximate a good tempo value for your system (see 5.4 - TIMECHK). (UPDATED) /C = the song's starting tempo is determined by a processor speed determining routine. /S = same as /C, except the status line "PLAYPOLY.EXE: Checking processor speed..." is not displayed. Note: If no extension is given on <file1>, PLAYPOLY assumes ".PLY" (for "poly" or "play"). Examples: to play a file named "SIMPTEST.PLY": PLAYPOLY simptest to play a file named "ODE.JOY" PLAYPOLY ode.joy to play a file named "INVENT13.PLY" at tempo = 512 PLAYPOLY invent13 512 to play a file named "INVENT13.PLY" and set the tempo according to the processor speed PLAYPOLY invent13 /c 5.0 OTHER POLYPHONIC MUSIC PROGRAMS ------------------------------- 5.1 AUTOHARP -------- As you may have noticed, several other mysterious programs have reared their ugly heads in this package. The first one, AUTOHARP is an interesting attepmt to breathe creativity into the PC speaker. Run it by entering AUTOHARP at the DOS prompt (in the drive/ directory where AUTOHARP.EXE is located). The keyboard layout screen comes up. To use this program, play your favorite chord progression by pressing the keys representing the chords you want. The top row of the keyboard (numbers) will play all your major chords. The next row plays minor chords, and the third plays diminished chords. By pressing <Shift> along with any key used plays a seventh of the chord in question. For instance, to play a G7 chord (that's G DOMINANT 7, to be specific), press <Shift '-'>. One other note: the tempo of the chord was set in the POLYCHRD.H include file and its a good speed for an IBM PCXT but may be way too fast for a quick processor. If you wamt to change the tempo modify the source code and recompile it. Side note: the way in which all those chords were defined is kind of nasty (they're defined in POLYCHORD.H). A much better solution for chord playing would be to have some sort of template for the form of each chord, and then make a key change appropriately. A discussion of the procedures called in AUTOHARP.C can be found in 6.1 - THE LIBRARY ROUTINES. 5.2 LOOPPOLY -------- This program is identical to PLAYPOLY.EXE in every way except that at the end of a song it plays it over if a key has not been pressed. This is useful in batch files while waiting for user input. One other note, the ascii value of the key pressed which ended the program is returned in the DOS variable "errorlevel", and can be accessed in batch files. 5.3 SOUNDEFF -------- This program just uses the Polyphonic Music library function "tritone()" to sound as much like an airplane (with a propellor) (or something else very peculiar) as it can. 5.4 TIMECHK ------- TIMECHK.EXE is a very useful tool in the Polyphonic Music world. Not only will it benchmark your computer, but it gives you an accurate tempo value to set playback of your ".ply" files. You run TIMECHK.EXE by typing TIMECHK at the DOS prompt and pressing enter. After a few seconds of processor intensive checking routines, TIMECHK returns the number of hundredths of a second that your processor completed these tasks in. Also it evaluates an approximate Polyphonic Music tempo value from this count. Just for comparison, I ran this on some of the machines around the office: Hund. of Secs. Poly. Tempo IBM original PC 45 465 Turbo XT clone 20 1024 IBM original AT 14 1462 IBM PC + 286 charge card 13 1706 IBM PS2 model 50 8 2560 286 machine 6 3413 386 machine 3 6820 The best use for this value is in making a batch file for your player files. For instance, if you had the 386 machine, you could call PLAYPOLY with a batch file PLAY.BAT that looks like the following: PLAYPOLY %1 6820 Note: If your computer is so fast that the hundredths of a second value is 2 or lower, you may have to experiment with large tempos (7000 or above) to find the correct value for your computer. A discussion of the C functions used in the source code of TIMECHK can be found in section 6.1 - THE LIBRARY ROUTINES. 6.0 USING THE POLYPHONIC C LIBRARY ------------------------------ 6.1 THE LIBRARY ROUTINES -------------------- The Polyphonic library consists of several functions that can be directly accessed within your C program source code and can be then linked in to your executable modlues. Since not all C compilers are the same, I've included both the .LIB file (POLY.LIB) containing all the enhancement functions, and its component .OBJ files. All the functions are defined in the header file POLY.H, and are supported in POLY.LIB. Within this package only near pointers are accounted for. Any LARGE structures will probably not work. You can order the Large memory model versions of these functions (see the text file included in this package: REGISTER.TXT). Here are descriptions of the Polyphonic Music functions: ------------------------------------------------------------------- #include <poly.h> int playpoly(plyfilename, defaulttempo) char *plyfilename; -- DOS path to play int defaulttempo; -- beginning tempo Object module: polyfunc.obj+poly.obj Description: The playpoly routine, when passed a legal filename (of the proper ".ply" type), and a beginning tempo, will play the three- voice song defined by the data in the ".ply" file. The playpoly routine can only read files of the type created by the MAKEPOLY.EXE program. If a file extension is not specified in the string plyfilename, a ".ply" is assumed. The default tempo must be in the range of 1 (very fast) to 65535 (very slow). This value is the starting tempo of the music file when played. (UPDATED) This routine will allocate memory and read in the file. If successful, it will close the file and play the entire file until completion. Then the allocated memory is freed. A keypress may abort the playing if such an action was provided for in the text version of the song (see 'K' command, section 3.23 - TEXT FILE FORMAT / SYNTAX). Return value: playpoly() returns a 0 (zero) if no errors occured during play. If an error does occur, an appropriate message is written to stderr, and a value of -1 (0xFF) is returned. See Also: looppoly(), polytempo() Example: #include <stdio.h> #include <poly.h> main() { printf(" 'Ode to Joy'. Press any key to stop repititions.... "); while (!kbhit()) playpoly( "ode", polytempo(10,250) ); printf("\r\n"); } ------------------------------------------------------------------- #include <poly.h> int looppoly(plyfilename, defaulttempo) char *plyfilename; -- DOS path to play int defaulttempo; -- beginning tempo Object module: polyfunc.obj+poly.obj Description: The looppoly routine, when passed a legal filename (of the proper ".ply" type), and a beginning tempo, will play the three- voice song defined by the data in the ".ply" file. It will play the song reptitively until a key has been pressed. The looppoly routine can only read files of the type created by the MAKEPOLY.EXE program. If a file extension is not specified in the string plyfilename, a ".ply" is assumed. The default tempo must be in the range of 1 (very fast) to 65535 (very slow). This value is the starting tempo of the music file when played. (UPDATED) This routine will allocate memory and read in the file. If successful, it will close the file and play the entire file until completion. If a key has not been pressed, it will start playing again. When a key press is detected, the allocated memory is freed. The keyboard is only checked every time the song ends! A keypress may abort the playing DURING the song if such an action was provided for in the text version of the song (see 'K' command, section 3.23 - TEXT FILE FORMAT / SYNTAX). Return value: looppoly() returns the ascii/scan value (getch()) of the keypress detected. If an error occurs, an appropriate message is written to stderr, and a value of -1 (0xFF) is returned. See Also: playpoly(), polytempo() Example: #include <stdio.h> #include <poly.h> main() { printf(" 'Ode to Joy'. Press any key to stop repetitions.... "); looppoly( "ode", polytempo(10,250) ); printf("\r\n"); } ------------------------------------------------------------------- #include <poly.h> unsigned timetest(sizechk) int sizechk; -- number of nodes to test Object module: polyfunc.obj+poly.obj Description: The routine timetest() is used to determine the current processor's speed. The function itself does several processor intensive tasks on an array of size sizechk, and returns the amount of hundredths of seconds required by the processor. The sizechk parameter determines the size of a mallocated array and thus the complexity and length (in time) of the test. The larger this value is, the longer the test will take, the more memory it will require, and the more accurate the return value will be. Return value: timetest() returns the number of hundreths of a second required to complete several processor intensive routines. On fast machines, sizechk values below 300 can often return 0. See also: processval(), polytempo() Example: #include <stdio.h> #include <poly.h> main() { int numnodes; printf("How many nodes to test? "); scanf("%d", &numnodes); printf("\r\n"); printf("Test completed in %d hundreths of a second.\r\n", timetest(numnodes)); } ------------------------------------------------------------------- #include <poly.h> unsigned processval( times, nodes ) int times; -- number of times to run test int nodes; -- number of nodes to use Object module: polyfunc.obj+poly.obj Description: This routine runs the timetest() routine the number of times sent in the 'times' parameter using arrays of 'nodes' size. It then returns the average of all the tests to give a processor dependent value which can be used to portably move your programs from computer to computer, adjusting program speed by means of a ratio of processor value to your original value. This technique was used in the PlayPoly routines. Return value: The amount of hundreths of a second, on average, the processor took to do the timetest() function 'times' times, with 'nodes' nodes. See also: timetest(), polytempo() Example: SEE the included file TIMECHK.C for an example of this routine. ------------------------------------------------------------------- #include <poly.h> unsigned polytempo( times, nodes ) int times; -- number of times to run test int nodes; -- number of nodes to use Object module: polyfunc.obj+poly.obj Description: This routine runs the timetest() routine the number of times sent in the times parameter using arrays of nodes size. It then returns an approximate value which is the optimum polyphonic tempo for the current processor to play at. This function allows portability of all the PlayPoly routines that require a tempo value, as the processor which is about to do the playing can be tested for speed first. This technique was used in the PlayPoly routines. Return value: The approximate optimum tempo for the PlayPoly routines to play at. (note: this function involves division and if the processval() function returns a 0 because of a very fast processor, this function will cause a division by zero error) See also: timetest(), processval() Example: SEE the included file TIMECHK.C for an example of this routine. ------------------------------------------------------------------- #include <poly.h> void poly( song ) (UPDATED) int *song; -- array of ".ply" format music to play Object module: npoly_s.obj Description: This routine plays the array of integers pointed to by song. This routine drives the PC speaker. The integer array is in a special format. Each value in the array means a specific command to the function. THE FIRST VALUE IN THE ARRAY IS THE TEMPO TO BEGIN PLAY AT. The constant values below are defined in the POLY.H file. The value that accompanies each comand is ORed (|) into the low 13 bits of the integer. A value of: Means: TCHANGE modify the starting tempo (see UPDATE.TXT with value being equivalent to the n in the updated version of the Tn command) V1 set the frequency of voice 1 to value V2 set the frequency of voice 2 to value V3 set the frequency of voice 3 to value KBCHECK check the keyboard buffer to see if a key has been pressed DUR play the three voices (set by V1..V3) for a duration of DUR * Current_Tempo STOP quit playing, return to calling program A song is played by setting the tempo, setting the three voices, and setting the duration (which then plays the three voices), until a STOP value is encountered. Return value: There is no return value. See also: tritone(), playpoly() Example: SEE the included file AUTOHARP.C and POLYCHRD.H for an example of this routine. ------------------------------------------------------------------- #include <poly.h> void tritone(tempo, v1, v2, v3, duration) int tempo; -- the tempo to play at int v1, v2, v3; -- the three voice frequencies int duration; -- the duration of the 3 voices Object module: ntrit_s.obj Description: This function plays three notes simultaneously on the speaker. The tempo value is usually an static variable which applies throughout the program and is processor dependent. For best results in frequencies, use the defined values in the POLY.H file. This function can be used for music or sound effects. Return value: There is no return value. See also: poly(), playpoly(), polytempo() Example: SEE the included file SOUNDEFF.C for an example of this routine. 6.2 USING THE POLYPHONIC MUSIC LIBRARY ---------------------------------- In order to use the Polyphonic C routines, insert them as you normally would into your source code (for an example, see any of the ".c" files included in this package). Next, compile your source code to object modules (".obj" files). In other words, compile WITHOUT linking. Finally, if you are using Microsoft C, link your object modules to the POLY.LIB library (as well as to the standard library). This step may not work with other brands of C compilers, so I've included the .OBJ files included in POLY.LIB. If you can't use the POLY.LIB or it doesn't work, link your C source files to the necessary object files (each function's necessary object files are listed before their description in section 6.1 - THE LIBRARY ROUTINES). This usually involves using a '+' command with your linker. For example: (taken from the file POLYCOMP.BAT) cl /c myprog.c --> compiles without linking (Microsoft C) link myprog,,,+poly; --> links myprog.obj with standard library and also uses poly.lib (Microsoft Linker) myprog.exe --> runs myprog If you use just the object files: cl /c myprog.c --> say myprog calls playpoly() link myprog+polyfunc+poly_s; --> link necessary object files myprog.exe --> run program 6.3 HOW TO USE THE LIBRARY ROUTINES ------------------------------- PlayPoly/LoopPoly: These functions need a legitimate ".ply" file to play. First, type in the music you want to play in the text format outlined in section 3.23. Make sure you place the 'K' command wherever necessary (to abort on keypress). It is suggested that you use the 'K' command in rests or at the end of phrases or measures, since it may take a small time interval to scan the keyboard (but usually this is not noticable). Also, be generous with them because your program user probably does not want to have to wait until the end of several measures for the program to continue. Second, compile the text file to a ".ply" file format using the included program MAKEPOLY.EXE. Third, use the path of the file in a call to the playpoly()/ looppoly() functions (see section 6.1 - THE LIBRARY ROUTINES). Fourth, compile and link your C program as described above (section 6.2). Poly: This function needs a legitimate array whose members are a list of integers in the ".ply" format. There are two ways to make this integer array. One is to load the array from a ".ply" file into memory (see PlayPoly/LoopPoly above for how to obtain the file). The second way is to hard code the music into your source code. Using this method has the advantage that the music takes up no external files, it is stored within the executable program itself. The way this second method is implemented is as follows: (UPDATED) 1. Define an integer array, 2. Fill it with the ".ply" values making up your song (this involves a certain amount of derivation), 3. Call poly() with the array pointer as a parameter. The way in which you fill the array with ".ply" values (step 2 above) is as follows: 1. Use the defined values created in the POLY.H file. 2. Set the tempo by plugging a tempo value into the array (an unsigned integer in the range of 1 to 65535). 3. Set the voices by plugging (Vn | voicefreqency) into the array (where 'n' is '1', '2', or '3'). You can use the frequency values defined in POLY.H. They are set up by nameofnote_octave, e.g. C sharp in the middle octave (the one with middle C in it) = CSHA_M. Set these defines according to your usage. Note: multiplying these numbers by 2 raises one ocatve, and dividing by 2 lowers one octave. 4. Set the duration of the notes by plugging (DUR | notelength) into the array. This will play the last defined voice values for the duration given. If any voice was not defined it will use the last frequency given. If there was never any value defined for any one voice it will play 0 (silence) for that voice. 5. Check for keypresses at any point by plugging (KBCHECK) into the array 6. Continue steps 3 - 5 (use TCHANGE | changeval as described in UPDATE.TXT to change the tempo in the middle of the song) until the song is completely hard coded. 7. Plug the last value (STOP) into the array For an example of this, see the header file POLYCHRD.H which defines the play of several three-note chords as if they were songs. Tritone: Use this function exactly as you would Poly, except send the VALUES of tempo, v1, v2, v3, and duration as parameters, NOT as an array. This function does not check for a keypress and a STOP value is not necessary since it stops once the duration expires. TimeTest/ProcessVal/PolyTempo: Use these functions to test the speed of a processor. They should be self-explanatory. 7.0 AUTHOR'S NOTE ------------- 7.1 PROGRAM DEVELOPMENT ------------------- The idea for this program first came the time I excitedly downloaded PIANOMAN.ARC from my favorite bulletin board. I impatiently loaded up the program waiting to see what one unknowingly deceiving uploader penned as "Plays polyphonic music!". When it loaded up I was sorely disheartened, as the pianoman was as far from a piano as a computer could be (well, next to having no speaker at all). Then one day I noticed a file that said VMUSIC.ARC "plays notes simultaneously". I had to check it out. And sure enough, it did what it claimed. It did not "simulate" three voices by playing three notes real fast through one voice. All three voices were there! This interested me and I played a little with the program. The time came when I wanted to use the possibility of three voices in a program I was writing. VMUSIC couldn't help me because it was unable to be accessed from C easily and quickly (not to mention it was copyrighted!), so I called up Ted Holden, the writer of VMUSIC. He didn't give me any code, but he referred me to the work of Steve Muenter. This was the guy who wrote the low- level technique for three voices. So, I got a copy of this assembly code and I hooked it up to C. I thought that a music compiler (putting the music into raw form for quick playing) would be a good idea, so I wrote MakePoly. I wrote it so that the three voices could be implemented into C. Basically this is the end result. The C enhancement routines provided in this package expand on the original concept and applications of three-voice music. And there is even more in the works (from Mr. Holden as well as myself -- see 7.4 - PROGRAM ENHANCEMENTS). Every thing in this package was written in either C or assembly (here's your free plug, Microsoft (5.1 to be exact)). * Three voice technology first started with Steve Muenter (as far as I know). He created a cryptic BASIC interface with a function similar to the poly() function in this package. His program played the song contained in the file SIMPTEST.PLY. The form it is in now is not very far from the original form in was in! Ted Holden crystalized this idea by allowing imitation BASIC commands in ascii text files to be played. * 7.2 PROGRAM FEATURES (UPDATED) ---------------- Both MAKEPOLY/PLAYPOLY and VMUSIC use the Basic-like commands to read and play three-voice music. They both are good music writing/composition tools. In the latest version of VMUSIC which is propogating around the nation's bulletin boards, Richard Pierce scored lots of Bach pieces and offered some comments to Ted Holden. In one of the README files Ted responds directly to Richard Pierce's suggestions. I'd like to do the same (my comments delimited by **'s): "There are some obvious ways (to me, at least) vmusic could be enhanced. This is contradictory to the concept of vmusic as, really, a toy program (with no intention on my part to denegrate it or the authors efforts). Many of the suggestions I have would be satisfied by MIDI sequencer programs. I doubt that the author had any inkling that vmusic would be put to such efforts as I have here. Be that as it may... Check!> Tempo Implementation of the Basic "play" command for tempo 't' would be very useful. Several of the pieces performance style could hve been immeasurably helped by being able to implement even incremental changes of tempo, much less true accelerando and ritardando. ** Incremental tempo changes are supported in this version... (see UPDATE.TXT) ** Check!> Triplets True triplet notes (where three notes are played in two beats) could have made some of the pieces far easier, and would have encouraged me to try others. One way that this could be noted in the music source would be some convention that would group the triplets together, such as: l8 v1o4 (efe)3 (ded)3 c4 v2o3 c<b >cd e4 where the triplet eighth notes like "efe" are played three against the normal two eighth notes "c<b" in a normal 3/4 time measure. The extension of this to sixth groupings "(......)6" and even seventh groupings "(.......)7" would enable many other pieces to be simply coded (the latter being true for the first movement of Bach's Partita #6). ** MAKEPOLY will allow "simulated" triplets. The manner in which this is accomplished is the following: Every note length in the <textfile> is first converted to a real time value. Specifically, Note Length: 1 2 4 8 16 32 64 - is converted to - Real Time Duration: 64 32 16 8 4 2 1 (the formula is RTD = 64 / NL) So, if you time your triplets in real time, and then set your note length accordingly, you can fake them. For instance, say you want a triplet for eighth notes. This would be equivalent in real time to 2 eighth notes, i.e. real time = 8+8 = 16, so your three notes would need to add up to 16. Let's use 5, 5, and 6. Since NL = 64 / RTD, and 64/5 = 12.8, and 64/6 = 10.67, use the notelengths, 13, 13, and 11, which add up to (when applied through the original formula, and rounded) 16. This works only because MAKEPOLY rounds the RTD derived from the formula. Try it! This example is realized in the file TRIPTEST.SNG. They sound like triplets to me! ** More voices Simply said... ** It is possible. I tried four (have capability for up to five) but the noise level was too much. I'll continue work on this! ** Platform independence It would be nice to be able to detect the speed of the machine, then set the tempo and pitch parameters automati- cally (or at least scale them) so that the same piece would sound the same on different hardware. Check!> ** PLAYPOLY currently offers this capability (see the command line parameter /C, section 4.22 - STARTING PLAYPOLY / COMMAND LINE) for playing songs which don't change tempo internally. This option has not been fully tested to see whether it reproduces pitches perfectly or just scales them (most likely the pitches are only scaled). A better speed detector would be nice (one that plays silence for instance!) ** Syntax checking A more intelligent parser would help debugging. For example, if vmusic had some knowledge of the measure length, it could detect missing or excessive notes in each measure. ** MAKEPOLY simply plays silence for a voice when a voice's info runs out. If you know what the piece sounds like, you should be able to detect slips in the voices. Although, an idea is in the works which, when implemented, will inform the user that one voice is shorter than another. Also: use the comment delimiters to section off pieces of the music. This allows focusing in on certain parts and you can then easily determine what's wrong. Never thought I'd be debugging an opera! ** Note Style Implementing the Basic "play" command for setting note style, such as legato, portamento and staccato, would make coding easier. ** One possible alternative is to play half of the value of the note and then rest the other half (staccato). I beleive these styles are possible. Explain what exactly the terms mean, and I'll have a go at them in upcoming versions ** Check!> Equal voices In some of the more complex pieces (such as the trio sonata), the second and third voices get lost beneath the more predominate first voices. All voices should have equal weight. ** 'This version of MAKEPOLY doesn't account for this but I have some ideas of ways to attempt this. Hopefully the next version will have conquered this problem.' - I said last (1.00) version. And it has... see UPDATE.TXT for details on equal voices ** ." 7.3 PROGRAM INFO ------------ MakePoly was written entirely in Microsoft C 5.1. In its finished form it is rougly 20K of source code. PlayPoly was written in Microsoft C 5.1, and linked to and external function written in Microsoft Macro Assembler 5.1. Both programs use dynamic memory for note storage, so the only limitation to song length is the amount of available memory. (Large memory model only, the small memory model has an upward limit of about 64K). Updated versions will be produced even if the amount of user feedback is minimal (in other words, PLEASE FEED BACK! Your comments are greatly wanted/apprieciated!). 7.4 FUTURE ENHANCEMENTS ------------------- Other than the enhancements mentioned in the discussion with Richard Pierce in section 7.2 - PROGRAM FEATURES, I personally am dedicated to see the following enhancements come to the world of three voice IBM music: * Functions to add three voice capability to: BASIC PASCAL, and any other requested languages (Note: the poly() function, in its present form, may may very well work for Pascal. I have yet to try it, but I ask anyone who uses Pascal to feel free to explore! I will attempt this if and when I get Turbo Pascal 5.5!) * The ability to work appearantly simultaneously while other functions are doing their thing (this is the "DOS-world-possibility" mentioned in section 7.2) * The "REPEATED MEASURE" ability for MAKEPOLY * For AUTOHARP type programs, a sensitive assembly key- board parser which plays a chord until a key is released (not just repeating the key). * A simple sequencer-type program that let's you edit a ".ply" file without knowing how to read music! (the keyboard would have to have assembly-type instructions as described for AUTOHARP above so the program could sense when keys were pressed and released.) * What would be really great is to be able to tune the player to concert pitch. 7.5 AUTHOR'S CORNER --------------- Let me just tell you a little about myself... I am 19, a Computer Science Major at the University of Texas. I also work for the Department of Verteran's Affairs, working with (what else) PC's. I am a programmer, and a serious musician. I play the guitar primarily, but I also have a great love for piano and the drums (trapset). I can't deny but that the Lord has been very instrumental and creative in my life. He has given me peace, joy, and love I never knew before I knew Him (and believe me, I searched!). Not only that but He has specifically answered my prayers and spoken through me. I give every waking moment to Him, and He satisfies me more than the world ever did! So if you have any comments, questions, advice, suggestions, or obscene remarks about what is present in this package, PLEASE contact me! Edward ("Eddie") Grigassy 2304A Riverside Farms Rd. Austin, TX 78741 (512)385-1368 On Compuserve: 73207,3140 Here is the address of Ted Holden, author of VMUSIC (obtainable on Compuserve {go ibmnew, music section}): Ted Holden HT Enterprises 1947 Storm Dr. Falls Church, Va. 22043 703 760-9713 And here is the address of Richard Pierce, the arranger of the many Bach music files (playable through MAKEPOLY and the other Polyphonic Music play routines presented here) included in the latest VMUSIC package (some were reproduced here): Richard Pierce 17 Sartelle Street Pepperell, Ma 01463 Technical Stuff: ---------------- If you enjoyed, used, or even loved this package, please consider a contribution of $20 or of any size. This package has been designated as ShareWare by the author (E. Grigassy); it serves as a demo for the more powerful later versions of Polyphonic Music, the Large memory models of the poly.lib functions. (see REGISTER.TXT), and the registration releasing full rights to the registeree (is that a word?). Registration Information: Polyphonic Music is distributed as User-Supported software. You are free to copy and distribute this software freely, however, if you find it of use to you, you are encouraged to register your copy. Registering your copy of the software helps the author continue to provide professional quality software at very reasonable prices. The Basic Registration is $5.00 and includes royalty-free use of library functions, unlimited technical support, and information about low-cost upgrades. All materials are shipped on 5.25-inch floppy diskettes. If you require 3.5-inch floppies instead, there is an additional $2.00 charge covering the cost of the diskette itself. Non-U.S. orders need to include $5.00 extra to cover additional shipping and handling charges. Checks and money orders must be drawn on a U.S. bank. Please send all payments payable in U.S. Dollars. Print the registration form, REGISTER.TXT, or include on a piece of paper your name, address, phone number, and requested items, and send it along with your payment to: Edward Grigassy GrigaSoft Productions 2304A Riverside Farms Rd. Austin, TX 78741 Microsoft(R), MS(R) are registered trademarks of Microsoft Corporation. IBM(R) is a registered trademark of the International Business Machines Corporation. All versions of VMUSIC (vm0389.exe is latest as of writing) are Copyright HT Enterprises / Ted Holden The files: PLAYPOLY.EXE, MAKEPOLY.EXE, LOOPPOLY.EXE, AUTOHARP.EXE, TIMECHK.EXE, AUTOHARP.C, TIMECHK.C, POLY.H, POLYCHRD.H, POLY.LIB, POLY_S.OBJ, TRIT_S.OBJ, POLYFUNC.OBJ, and any of the original source code not mentioned above are Copyright (c) 1989 Edward P. Grigassy / GrigaSoft Productions. None of these files or procedures may be used in any commercial software nor may they be bought or sold without the explicit written permission of Edward P. Grigassy / GrigaSoft Productions. Polyphonic Music (TM) is a trademark of GrigaSoft Productions. Disclaimer: ----------- Edward Grigassy / GrigaSoft Productions is not responsible for any damage or loss of property caused by the software in this package. This package is provided AS IS and no guarantee is made by the author/owner for the safety of the user's property. All the documentaion included in this package is subject to change at any time and in no way reflects any commitment on the part of the author/owner.