Hall of Fame

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

/ Hall of Fame / HallofFameCDROM.cdr / misc2 / pmusic12.lzh / POLY.DOC < prev next >

Wrap

Text File | 1989-12-08 | 39KB | 822 lines

Polyphonic Music Package ver 1.20 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) For more personal info see section 7.5 of this manual. INTRODUCTION ------------ Welcome to the world of polyphonic music! Recently several programmers working separately 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 PlayKb Player ........................................... 4.0 Explanation .......................................... 4.1 Use .................................................. 4.2 Requirements ...................................... 4.21 Starting PlayKb / Command Line .................... 4.22 Other Polyphonic Music Programs ......................... 5.0 AutoHarp ............................................. 5.1 LoopKb ............................................... 5.2 Author's Note ........................................... 6.0 Program Development .................................. 6.1 Program Features ..................................... 6.2 Program Info ......................................... 6.3 Future Enhancements .................................. 6.4 Author's Corner ...................................... 6.5 1.0 WHAT'S INCLUDED --------------- Included in this current version of Polyphonic Music are the following files: README .1ST -- Read this file for instructions on getting started quickly MAKEPLAY.BAT -- Batch file to compile and play a .sng file PLAYALL .BAT -- Batch file to compile all songs and play all songs (only compiles the first time) AUTOHARP.C -- Example of a simple program that inter- *.H -- faces with the Polyphonic Music C language library LOOPPOLY.PAS -- Example of a program that interfaces with the Polyphonic Music Turbo Pascal routines PLAYPOLY.PAS -- Example of a program that interfaces with the Polyphonic Music Turbo Pascal routines -- The poly file player LOOPKB .EXE -- The poly file player that repeats a song until a key is pressed MAKEPOLY.EXE -- The textfile-to-polyfile compiler AUTOHARP.EXE -- Example program created with the Polyphonic music C language interface TRIPTEST.SNG -- An example song file that displays use of simulated triplets (also see FURELISE.SNG) *.SNG -- Various song files to play POLY .DOC -- The Polyphonic Music documenation (this file) REGISTER.TXT -- Shareware Regisration form UPDATE .TXT -- List of important additions/modifications in the lifetime of Polyphonic Music software 2.0 WHAT IS POLYPHONIC MUSIC? ------------------------- The Polyphonic Music programs are an innovative system for allowing TRUE 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 (PlayKb.exe) his/her songs, o A batch file enhancer, which can play three part music while waiting for a keypress, o A C programming language enhancer, which allows three voice music to be played within a C program until a keypress is detected, and o (UPDATED) A Pascal (specifically Turbo Pascal 4.0 and greater) language enhancer, which allows three voice music to be played within a Pascal program until a keypress is detected. [See section 6.4 - Future Enhancements for uses soon to be implemented!] 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/Pascal programs themselves. The second technique is only usable within C and Pascal programs. It involves defining the music to be played within the program (in array form). This second method may be preferable 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>] [/pval] 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) pval = (UPDATED) the frequency value for the pitch of Middle C. This pitch will determine every pitch (relatively) of the ".ply" file. It may be in the range of 1 (low) to 8191 (high); all other notes are derived off of this value, so values below 170 and above 7000 may have distorted frequencies at the low end and the high end of the spectrum respectively. See UPDATE.TXT for more information. (this value is optional). Some good values for different machines: IBM PC 543 XT 390 <default> AT 311 PS/2 253 286 189 386 137 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>. If pval not specified, MAKEPOLY assumes 390 (which is perfect pitch on my Turbo XT). Examples: to compile a file named "SIMPTEST.SNG": MAKEPOLY simptest to compile a file named "ODE" with a Middle C pitch of 195: MAKEPOLY ode. ode.ply /195 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; also "O0" causes an error, use "O1<") 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 -- eighth note 16 -- sixteenth note 32 -- thirty-second note 64 -- sixty-fourth note (note: n can be other values between 1 and 64, see 6.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 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 omission of 1 or more of them. Example: V1 -> sets up voice 1 to play the subsequent notes K -- (UPDATED) The K command is no longer supported since the creation of the polyfile playing function that checks for a keypress after each note. *..* (UPDATED) Allow a user comment. All text in between two asterisks 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 PLAYKB POLYPHONIC MUSIC PLAYER ------------------------------ 4.1 EXPLANATION ----------- The PLAYKB.EXE file, when run, plays a ".ply" file in polyphonic (three voice) sound until a key is pressed. 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 PLAYKB.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 PLAYKB / COMMAND LINE ------------------------------ To run PlayKb, make sure you are in the directory where PLAYKB.EXE resides. Enter the following command at the DOS prompt: PLAYKB <file1> [/c,/s,tval] 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: /C = the song's starting tempo is determined by a processor speed determining routine. /S = same as /C, except the status line "PLAYKB.EXE: Checking processor speed..." is not displayed. tval = the tempo you would like to set PlayKb to play at. If not given, PLAYKB assumes 1024. This can be any positive number ranging up to 65535. The lower the number, the faster the tempo. Note: If no extension is given on <file1>, PLAYKB assumes ".PLY" (for "poly" or "play"). Examples: to play a file named "SIMPTEST.PLY": PLAYKB simptest to play a file named "ODE.JOY" PLAYKB ode.joy to play a file named "INVENT13.PLY" and set the tempo according to the processor speed PLAYKB invent13 /c to play a file named "INVENT13.PLY" at tempo = 512 PLAYKB invent13 512 5.0 OTHER POLYPHONIC MUSIC PROGRAMS ------------------------------- 5.1 AUTOHARP -------- AUTOHARP is an interesting attempt 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 '-'>. 5.2 LOOPKB ------ This program is identical to PLAYKB.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. 6.0 AUTHOR'S NOTE ------------- 6.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 6.4 - PROGRAM ENHANCEMENTS). Every thing in this package was written in either C or assembly. * 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. * 6.2 PROGRAM FEATURES (UPDATED) ---------------- Both MAKEPOLY/PLAYKB 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 propagating 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 degenerate 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 have 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... ** Am working on a possible avenue of many, many more voices. It is very possible! ** 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!> ** PLAYKB 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). (UPDATED) The current processor speed test works with minimal user interface. It also uses more speaker speed dependent routines than the previous version providing for minimalsystem halts (which was fairly common in the old speed checking routines) ** 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. 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 believe these styles are possible (in fact I think playpoly plays entirely in legato, what do you think?). 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 (1.00) version. And it has... see UPDATE.TXT for details on equal voices ** ." 6.3 PROGRAM INFO ------------ MakePoly was written entirely in C. In its finished form it is roughly 20K of source code. PlayPoly was written in C, and linked to and external function written in assembly. The Turbo Pascal interfacing was implemented in Turbo Pascal 5.0 (thanks to the request and support of Al Dundead (sp?) in California!). 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/appreciated!). 6.4 FUTURE ENHANCEMENTS ------------------- Other than the enhancements mentioned in the discussion with Richard Pierce in section 6.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 * The ability to work apparently simultaneously while other functions are doing their thing (this is the "DOS-world-possibility" mentioned in section 6.2). I have written the routine to do this I just need help in figuring out how to run this routine every few clock ticks safely. * 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 (if anyone tunes their version of MAKEPOLY to concert pitch, let me know!). 6.5 AUTHOR'S CORNER --------------- Let me just tell you a little about myself... I am 20, a Computer Science Major at the University of Texas. I also work for the Department of Veterans 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 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 C & Pascal Polyphonic Music language enhancements (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. 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. Turbo Pascal (R) is a registered trademark of Borland International, Inc. All versions of VMUSIC (vm0389.exe is latest as of writing) are Copyright HT Enterprises / Ted Holden The files: PLAYKB.EXE, MAKEPOLY.EXE, LOOPKB.EXE, AUTOHARP.EXE, AUTOHARP.C, and any of the original source code not mentioned above are Copyright (c) 1989 Edward P. Grigassy / GrigaSoft Productions, all rights reserved. None of these files or procedures may be used in any commercial software nor may they be bought or sold (except by authorized Shareware / Public Domain distributors) 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 documentation 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.