PC-Online 1998 February

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

/ PC-Online 1998 February / PCOnline_02_1998.iso / filesbbs / dos / nbeta087.exe / PAGEPLAY.DOC < prev next >

Wrap

Text File | 1996-02-04 | 32.5 KB | 711 lines

PagePlay 1.34 (C) Copyright 1991,1994 Whirlwind Software Documentation (C) Copyright 1991,1994 Whirlwind Software Program and documentation written by Gerald T. Albion Date of Issue: March 27, 1994 Notice: NO WARRANTY! Gerald Albion and Whirlwind Software assume no responsibility whatsoever for any damage or loss caused by the use of PagePlay. By using PagePlay you assent to this condition and absolve Gerald Albion and Whirlwind Software of all liability for your use of PagePlay. PagePlay may not be "re-packaged" or "re-archived" in any way. If you receive this archive in anything other than a ZIP envelope, please report this to the author either at the address below or on the BBS listed at the end of this file. PagePlay may not be included on a CD-ROM or for-sale shareware disk without the express written consent of the author. PagePlay may not be uploaded to Big Blue & Cousins BBS (Victoria, B.C.) under any circumstances. PagePlay is not crippled or disabled in any way. It is distributed on the "honour system" as shareware. If you like and use PagePlay, please help make the shareware concept work, and send $5 to the following address: Whirlwind Software P.O. Box 480 South Joffre Victoria, British Columbia Canada V9A 6C8 If you send $12 (U.S. Funds) and your address, you will receive the full retail PagePlay package including the 17-page manual! This low, low price includes shipping within North America! Because PagePlay is uncrippled, there is no "key" file to be mailed, but if you include your Fidonet or Internet address with your registration, you'll get a note of thanks and confirmation of receipt. Purpose: PagePlay originated as a tiny program which could play sound files written for the SysOp Page function of RemoteAccess(tm) BBS version 0.03 or later. It now serves two purposes: (1) to give the page-music experimenter a more convenient way to test and debug his/her creations, and (2) to allow sysops of any BBS (that allows DOS drops) to use existing RemoteAccess PAGE.RA files, Maximus TUNES.BBS files, and (best of all) the more-advanced *.PPL files such as those included in PagePlay's distribution archive. PagePlay is 100% command-compatible with UFO Communications Engine. Usage: PAGEPLAY <filename.ext> <User's name 1> <Name 2> .. <Name X> <-d> <-mMaxTune> PagePlay normally requires that you enter the full filename with extension. If no extension is provided, PagePlay assumes .PPL. If no .PPL file exists, PagePlay will search for a .RA file. If there is neither .RA file nor a .PPL file, PagePlay searches for a file with no extension. If none of these exist, PagePlay will abort with an error. If no extension is provided, but a dot is provided, PagePlay assumes no extension. You may specify a User Name with as many names as you require. If you specify a user name, a message will appear: "You are being paged by ____ _______ " ...where the ____ _______ would actually be the specified user name. For the convenience of operators of Maximus-CBCS, PagePlay will strip any name that is "NLN". "NLN" is what Maximus generates when a user has no last name, e.g. a one-word pseudonym. Since most users and sysops agree that NLN is pretty ugly, it is stripped. If no user name is specified on the command line, then no message is displayed except the copyright notice. The -D optional switch enables "Debug Mode." Debug mode is useful for locating individual notes within a large music file. When Debug mode is enabled, striking ESC to abort the tune will produce an abort message with the line number of the note where the abort occurred. The -M optional switch specifies Maximus Mode. In Maximus mode, PagePlay will assume a Maximus-style TUNES.BBS file structure, in which any number of tunes can exist and be called independently. The -m and its parameter must be a single string, e.g. -mMarseillaise. The parameter is the name or "Yell Number" of the tune within your Tunes.Bbs that you wish to invoke. If a number is specified instead of a name, PagePlay assumes that the number represents a "Yell" name such as Yell1, Yell2, Yell6, etcetera. These names are not special in any way except that Scott Dudley has chosen to include them as alternate names in Maximus' sample TUNES.BBS file. The parameter is case insensitive. Examples: PAGEPLAY PAGE.RA PAGEPLAY DROID.PPL PAGEPLAY DROID PAGEPLAY TEST9 Uncle Ernie PAGEPLAY QUINT -d PAGEPLAY TUNES.BBS /m3 PAGEPLAY TUNES.BBS /mtinkle PAGEPLAY PAGE The first example would play the current RemoteAccess Page Music file (if any is present). The second and third examples both play DROID.PPL. The fourth example plays TEST9.PPL and informs the sysops that a user named Uncle Ernie is paging them. The fifth example plays QUINT.PPL and will display a line number if it is aborted. The sixth and seventh examples each play individual tunes from within a TUNES.BBS file. The sixth example will play the tune labelled Yell3, and the seventh example will play the tune labelled Tinkle. The last example looks for PAGE.PPL. If it does not find it, it looks for PAGE.RA. If it finds PAGE.RA, PAGE.RA is played. General Notes: A song being played can be stopped at any time by striking ESCAPE. If debug mode is enabled with the -D command-line switch, the line number will be displayed. As of version 1.33, holding either SHIFT key during play temporarily puts PagePlay in "Fast Forward" mode until you release the key. All of the commands listed below, and most of their parameters, can be abbreviated to just their first character. PagePlay is oblivious to DesqView and other multi-taskers. It has been tested under DesqView and shown no particular hostility towards DesqView, although PagePlay's own performance may be affected by the use of a multi-tasker. If you are experiencing short "gaps" or pauses in PagePlay's musical output, and you are not using a multi-tasker, it could be that the disk from which you are reading the music file is slow. Try optimising your hard disk with one of the many de-fragmenters available, and, failing that, try placing your music file(s) on a RAMDisk, where there should be no such delays. TSRs can also affect PagePlay's performance. PagePlay will ignore anything after the fortieth column in a line. Since most of PagePlay's commands can be abbreviated to one letter, this should not pose a problem. Comments, of course, can be as wide as 255 columns. File Format: Please consult your Maximus documentation for information on the TUNES.BBS File structure. PagePlay and RemoteAccess use raw text. PagePlay 1.32 supports several basic commands, with parameters. Briefly, here they are. TONE [frequency in Hz] [ticks] This command sounds a tone of the specified frequency for the duration specified in the second parameter. By default, each "tick" is 10 milliseconds in length, for RemoteAccess compatibility. This command is supported by RemoteAccess. ╔══════╦═════════════════════════════════════════════════╗ ║ ║ Frequencies ║ ║ Note ║ 0 1 2 3 4 5 6 7 8 ║ ╟──────╫─────────────────────────────────────────────────╢ ║ A ║ 27 55 110 220 440 880 1760 3520 7040 ║ ║ Bb ║ 29 58 116 233 466 932 1864 3729 7458 ║ ║ B ║ 30 61 123 246 493 987 1975 3950 7901 ║ ║ C ║ 32 65 130 261 523 1046 2092 4185 8370 ║ ║ C# ║ 34 69 138 277 554 1108 2216 4433 8867 ║ ║ D ║ 36 73 146 293 587 1174 2348 4697 9394 ║ ║ Eb ║ 38 77 155 311 622 1244 2488 4976 9952 ║ ║ E ║ 41 82 164 329 658 1317 2635 5271 10543 ║ ║ F ║ 43 87 174 349 698 1396 2792 5584 11169 ║ ║ F# ║ 46 92 184 369 739 1479 2958 5916 11833 ║ ║ G ║ 48 97 195 391 783 1567 3134 6268 12536 ║ ║ Ab ║ 51 103 207 415 830 1660 3320 6640 13281 ║ ╚══════╩═════════════════════════════════════════════════╝ These note values are approximate, especially at the low end. WAIT [ticks] This command simplay pauses with silence, for the specified number of ticks. This would be used for a musical rest or a dramatic pause. This is the only other command, aside from TONE, which is RemoteAccess compatible (because RemoteAccess only provides two commands). MUSIC [note] [length] [dot] [3 (triplet)] [tie] Examples: Music F#3 Whole M Eb4 Eighth 3(Triplet) Complete Syntax: [note] may be two or three characters. If two, the first character expresses a musical note in the range [A..G], and the second character expresses the octave in which that note is played, in the range [0..8]. If [note] is three characters, the THIRD character represents the octave. The first character is the note, and the second character represents the accidental - either sharp or flat - to be applied to the specified note. Acceptable syntaxes: ( x is the octave in the range [0..8] ) Case is not significant. Ax D#x Rest (or just "R") Ebx A#x Bbx Ex Fbx Bx Cbx Fx E#x Cx B#x F#x Gbx C#x Dbx Gx Dx G#x Abx Length is one or more characters, of which only the first is significant: D: Double-Whole W: Whole H: Half Q: Quarter E: Eighth S: Sixteenth T: Thirty-second 6: Sixty-Fourth U: Utility Duration The utility duration is a user-defined duration. See the "U" command below for details. When ZPEED is 10 (the Pageplay default), a whole note is 960 milliseconds (96 RA 'ticks') in duration. Dot is one or more characters, of which only the first is significant. If 'D' is the first letter of any parameter of the M command after and including the third, the note's length will be "dotted" or extended by half again its specified duration. 3(Triplet) is one or more characters, of which only the first is significant. If '3' is the first letter of any parameter of the M command after and including the third, the note's length will be treated as a triplet, or shortened to two-thirds the specified duration. T (Tie) is one or more characters, of which only the first is significant. If 'T' is the first letter of any parameter of the M command after and including the third, the note will be "tied" to the following note, or in other words, the speaker will not be turned off at the completion of this note. MUSIC (which may be abbreviated to M) is not supported by RemoteAccess. -TIE ON -TIE OFF This command may be abbreviated to -T (not just to - like most other commands). -TIE ON will force Tie mode to be on full-time, overriding any TIE parameters associated with music notes. -TIE OFF returns Tie mode to normal - most notes are not tied, and notes that have ties indicated are tied. SWEEP ON SWEEP OFF SWEEP DEST [note] This command "sweeps" or "bends" the sound from subsequent notes to the specified "destination" note, and automatically assures that the sweep will take exactly the specified number of ticks. If the end frequency is less than the start frequency then the sweep will be from high to low. Use SWEEP DEST (or S D) followed by a note (as described above under the MUSIC command) to specify the note which following notes will glide to. Use SWEEP ON (or S ON) to enable the sweep function. Use SWEEP OFF (or S OFF) to turn sweeping off. SWEEP can be used in conjunction with the ARPEGGIO and VIBRATO commands below for many special effects. NOISE ON NOISE OFF This command causes PagePlay to play subsequent notes using a "random" noise suitable for sound effects or drum effects. The noise's average frequency is that of the note or tone being played. NOISE OLD NOISE NEW NOISE FACTOR [65000's-of-a-second] There are two modes of "noise" available: "old" and "new." The "Old" mode is left behind from previous versions of PagePlay for compatibility reasons. Since it uses a HLL pseudo-random algorithm, its noise effect is lost at specified frequencies above 3000 Hz. The "New" mode uses assembly language timing to generate true white or pink noise. The "Noise Factor" is the duration, in sixty-five-thousandths of a second, between updates of the speaker frequency. The default noise factor is 20 (which is equal to about 306 microseconds). On slower machines this setting may prove to generate too much loop overhead and will thus cause tempo distortion (noise will play slower than music). If this is the case, then adjust the noise factor so that it is larger. The larger the noise factor, the slower the updates but the lesser the overhead. As Noise Factor increases, the noise output by "new" noise sounds more and more like "old" noise. ZPEED [milliseconds per tick] This command lets you change the "tempo" of the piece without changing all the note durations for every note. By default (i.e. if ZPEED is never used) this value is 10, so that 100 ticks can occur each second, which is compatible with RemoteAccess. When using this to alert you of paging users, ZPEED can be used in a special version of your regular chat-music file to indicate a "special" user with an increased, more "urgent" tempo. ZPEED can also be potentially used to aid in sculpting sound effects not yet implemented in PagePlay... X-TRANSPOSE [Transposition factor] This command causes PagePlay's output to be raised or lowered - "transposed" a specified number of semitones. For example, if you include the following command: X 12 PagePlay will shift all tones up one octave. Similarly: X -24 ...will shift all tones down two octaves. UTILITY: This command specifies the duration, in ticks, of PagePlay's user-defined "Utility" duration. With utility durations, you can create durations not supported by PagePlay directly, such as quintuplets and septuplets. For example, to create a construct of five eighth quintuplets which, temporally, equal four eighths, you would calculate the number of ticks that those four eighths would use: Whole = 96 ticks Half = 48 ticks Half = 4 eighths ergo 4 eighths = 48 ticks Now divide 48 by five, to find the utility duration for each of your quintuplets: 48/5 = 9.6 Now, we can't have a fractional number of ticks, so we have some notes longer and some shorter. Utility: 10 Music C4 Utility Music D4 Utility Music E4 Utility Utility: 9 Music F4 Utility Music G4 Utility The above example shows how you can use the utility duration to make your quints equal 48 ticks exactly. There you have your quintuplet structure. This principle can be applied to virtually any type of non-standard duration. VIBRATO ON VIBRATO OFF VIBRATO DEPTH [depth] VIBRATO RATE [period] This set of commands will cause notes played to have a vibrato quality. The depth is the maximum frequency the note will be allowed to deviate from the specified start frequency. The "rate" (rate is a misnomer; it means "frequency" and what we are actually specifying is a period of time, which is the reciprocal of frequency) or period is the time required, in milliseconds, for the vibrato to complete one frequency cycle. The period is not affected by the ZPEED command. The software-generated waveform which produces the vibrato is triangular in shape. VIBRATO can be used in conjunction with SWEEP for effects, but not with ARPEGGIO (Arpeggio will automatically take precedence if both are specified). VIBRATO is not supported by RemoteAccess. ARPEGGIO ON ARPEGGIO OFF ARPEGGIO DEST [note] ARPEGGIO RATE [period] ARPEGGIO MODE ABSOLUTE ARPEGGIO MODE RELATIVE ARPEGGIO FACTOR [transposition factor] This command is very similar to VIBRATO except that the tone being played is modulated with a square wave (technically a pulse wave but it is square in duty-cycle) rather than a triangle. The result is a sound that can be made to simulate a two-part harmony. The DESTination is a note following the syntax of the note parameter of the MUSIC command above. The duration of the tone is in ticks, and the period of each arpeggio cycle, specified by the RATE paramter, is in milliseconds. The MODE parameter specifies whether Arpeggio will alternate to an absolute note (specified by the DEST parameter) or to a relative transposition (specified by the FACTOR parameter). By default, Absolute mode is used. In relative mode, you specify the offset to the current note, in semitones. Thus, if you specify FACTOR to be 12, the destination will always be one octave above the base note value. If you specify 7, the destination will be a seventh above. REPEAT [# of times] LOOP Example: Repeat 4 Music A4 Eighth Music A3 Eighth Loop This example will "play" the two music commands a total of four times. These two commands form a LOOP structure. You may place music commands, more structural commands or any other valid PagePlay commands in between REPEAT and LOOP. When PagePlay encounters a REPEAT statement, it knows to expect a LOOP statement somewhere further down the song. When it encounters the LOOP statement, it "goes back" to the line immediately following the REPEAT, and plays the same music again. This continues until the music between the REPEAT and the LOOP has been played the number of times specified in the REPEAT parameter. DEFINE [block number] END [block number] CALL [block number] These commands allow you to define and call a "block" of music - a musical sub-routine if you like. PagePlay allows up to 64 such blocks to be defined, and they are numbered from 0 to 63. A block may be re-defined elsewhere. DEFINE and END are used to define the beginning and ending of a particular block of music. CALL is used later, to play a block of music which you have previously defined. File Format Examples: Refer to the included files, "WHISTLE.PPL", "DROID.PPL", and the TEST*.PPL files, for examples of syntax usage and produced results. There are many other included music files with varying degrees of "shortcuts" in the syntax; all of them are perfectly valid. Note: The "Tocatta" tune included in TUNES.BBS is a verbatim conversion of one voice of a three-voice SIDPlayer file, and as such is quite imperfect. It is included mainly to illustrate the PP2MAX and the possible size of a TUNES.BBS tune... Revision History: 1.33 : Streamlined code a bit, cleaned up a few loose ends where PagePlay could conceivably leave a note playing forever after executing. Documentation clarified somewhat. A few new musics. Added "Fast Forward" mode - hit a shift key to activate it. Bundled PP2ANS, an admittedly imperfect but still- useful utility which makes ANSi music files for your BBS! 1.32 : Maintenance release. Improved memory efficiency. Documentation enhanced slightly. The 4000 line limit is now enforced at load time to prevent crashes. 1.3 : Extended NOISE command - including finally fixing it such that it actually outputs true noise (more or less...). Improved filename intelligence considerably. Added -TIE command for fulltime tie mode. 1.2 : Added Maximus-CBCS 2.xx compatibility with TUNES.BBS. Bundled PP2MAX, a PagePlay-to-TUNES.BBS conversion program. 1.1 : Added a Debug Mode. When the -D command line switch is used, aborting the tune with Escape will cause an "Aborted at Line..." message. Added a "Utility Duration" which can be any number of ticks from zero to 65535. Added 64th notes. Do not use them at fast Zpeeds - Your brain might explode. Added Transpose. Added "relative" arpeggio (or auto-octava, auto-fifth, auto-whatever) for automatic arpeggio destination transposition. Changed frequency base from A4=451Hz to A4=440Hz. Bundled PP2RA, a PagePlay-to-RemoteAccess conversion program. 1.0 : Final form of Version 1.0. Memory is now allocated only as needed according to the size of the file being played. 0.36τ: Refined blocking somewhat - if no parameter is given to the RAM END command, the last DEF encountered is assumed to represent the block to be ENDed. 0.35τ: Added looping and blocking commands. REPEAT..LOOP structure RAM gives an immediate loop of a finite number of iterations, while DEFINE..END defines a block of music which can be CALLed later. 0.29τ: Entire song is now loaded into memory first, eliminates timing RAM problems brought about by slow drives. Song is played from RAM, limit of 4000 lines set. 0.21τ: Changed syntax of Vibrato, Arpeggio, Sweep and Noise commands. This release of PagePlay is incompatible with the non-RA features of previous PagePlay versions. RA compatibility has been preserved. Existing RA page-music files may be enhanced using PagePlay commands. Streamlined even further. Although PagePlay's tempo may still be slowed somewhat on 4.77 MHz machines, the tempo inconsistency between normal play and arpeggio/vibrato notes has been eliminated. Added a text input buffer. As a result, Pageplay now requires an additional 4k in which to execute. The buffer should reduce the frequency and length of pauses in the music while PagePlay reads its data from the disk, particularly on floppies or very slow hard disks. Sweep and Arpeggio can now be used in conjunction for effects. Sweep and Vibrato can now be used in conjunction for effects. Arpeggio continues to sound its second note even during rests, for effects. To get a true silent rest, arpeggio must be turned off. PagePlay no longer assumes a music file extension of .RA when the extension is omitted, but now assumes .PPL. 0.11τ: First public release version. Added extended note-entry commands. 0.06ß: Generally refined and streamlined code for smaller size and faster execution. Should work better on slow machines now. Completed 91/03/17 17:00. 0.05ß: Added option to display name of user requesting chat. The user's name can contain as many words as necessary. For Maximus sysops who run pseudonym BBSes, the string 'NLN' is stripped (because it is UG-LY!) Completed 91/02/09 15:25. 0.04ß: Added Arpeggio for 2 way chords. 0.03ß: Added Vibrato. You now have to hit ESC to abort. 0.02α: Recompiled using Turbo Pascal 5.5 for faster execution and smaller size. Added key-press-to-abort. Added bidirectional adjustable sweeps. Added adjustable noise. Completed 91/02/05 23:30 0.01α: Wrote core basic functionality of PagePlay. First alpha release. Completed 91/02/05 01:05 Development notes: 1.34 Made some minor bug fixes. Fixed an octave transposition problem in PP2ANS. 1.33 This is really another maintenance release, which fixes a couple of little inconsistencies and other things which have been picking at me since the last release a year ago. Some of my work from one of those projects (the TMR Adlib Music routine) shows here in a couple of music files and a new "Fast Forward" feature which I found indispensible in TMR. Also, I had been planning to include an ANSi music player/convertor in this release but other projects have placed such a great demand on my time that only the convertor PP2ANS is included. It's still not perfect yet either but an X-Transpose comamnd here or there should be sufficient to correct for most of its problems; you'll hear what I mean when you play a converted ANSi file. I still think you'll find it tremendously useful even in its buggy form. Also you'll note that I have formed a company for distribution of my programs; no, I haven't sold out, you're still getting Gerald Albion's code and not some junior schmuck at XYZ Software Conglomerated Inc. 1.32 This is a "maintenance release" - which is Programmerese for a "bug-fix" release. Basically I have actually started enforcing the 4000 line limit - previously PagePlay would just lock the system if you tried to load a file bigger than 4000 lines. I have also observed that I have yet to see any music commands go past the 40th column on a line, so to save memory I have imposed a 40-column cutoff. This will halve the amount of memory that a song occupies. Yes, I know; I should just compile the lines on-the-fly into 2-byte commands rather than load the actual text into memory. Maybe later. There are a pair of new .PPL samples included in TUNES.ARJ; enjoy... 1.3 NOISE has finally been fixed. It took a high-speed precision timing routine in assembly to achieve, but the results are worth the effort. I, always a glutton for bells and whistles, couldn't resist including a parameter (NOISE FACTOR) which lets you make the "new" noise sound (somewhat) like the "old" broken noise. Also the new noise allows for an improved TINKLE.PPL paging file. 1.1 Just for the record, when you're programming entirely in integers, the Equal Tempered musical scale is your worst nightmare. Despite this, two new forms of relative transposition have been added. Also, if your tunes sound a little different under 1.1 than they did under 1.0, it's not your imagination. Up 'til version 1.1, there was a discrepancy between the frequency table in the docs and the actual speaker output: While the table gives frequencies based on A4 being equal to 440 Hz, Pageplay based its output on A4 = 451 Hz. As of 1.1, PagePlay uses the more widely accepted 440 Hz base. PagePlay has been tested with a Korg digital tuning reference, and on most machines it should be within one cent of perfect pitch (in octave 4) - any error will more likely be due to your system's background noise from the fan and hard drive! 1.0 At this date I have still not perfected the NOISE command. I have left it in place because some interesting effects can be attained with it as it is, as evidenced in TEST5.PPL. A later release of PagePlay _WILL_ include a true white-noise generator command IN ADDITION to the existing NOISE command. -=( T )=- Acknowledgements and Personal Notes from the author: Thanks to Allen Walker for his invaluable work in converting C-64 SID music to PagePlay format, so that I am able to provide many sample music files for your edification and enjoyment. Thanks to Patrick Wilson for putting the bug in my head to write this thing, and for numerous suggestions, which have been incorporated into PagePlay. Thanks to Richard Whittaker for trying out a completely untested program, putting his system at grave risk, just to beta-test PagePlay for me. Thanks to Craig Chamberlain and Harry Bratt for designing the SIDplayer program, after which PagePlay is modeled in some places. Finally, thanks to Rob Hubbard, for programming all that great music on the C-64. Maximus-CBCS(tm) is a trademark of Scott Dudley. RemoteAccess(tm) is a trademark of Continental Software. DesqView(tm) is a trademark of Quarterdeck Office Systems. SIDPlayer(tm) is a trademark of Compute! Books. Garfield(tm) is a trademark of Jim Davis/United Feature Syndicate If you have any questions or comments please contact Gerald Albion on Tommy's Holiday Camp BBS, or send netmail to 1:340/26 or email to ue075@freenet.victoria.bc.ca +1 604 380 6467 (2400-14400 HST) 1:340/27 +1 604 361 4549 (2400-14400 V.32bis) 1:340/26 24 Hours a day "In Stereo" -eof- Whirlwind Software P.O. Box 5874 Victoria, B.C. Canada V8R 6S8