THE SOUND-BYTE PROGRAM **** VERSION 1.00 **** Release Date: February 18, 1990 Copyright (c) 1990 by Structured Technology ===================================================================== NOTE: This version of the Sound-Byte program is Shareware and may be freely distributed so long as this text file accompanies the program and neither file is modified in any way. ===================================================================== WELCOME TO THE SOUND-BYTE! Welcome to The Sound-Byte program, a GEM based sound generator program for the Atari ST/MEGAST computers. The sound chip used in the ST line of computers is the Yamaha YM-2149 Programmable Sound Generator (PSG) chip. Some of the features of this chip are: o Three independent programmable tone generators, called Channels A, B and C which can be used to generate music and sound effects. o A programmable noise generator. o A programmable mixer for combining tone and noise sounds. o Programmable waveform envelopes for controlling channel volume modulation. o Two bi-directional 8 bit data ports which are used for output functions related to the floppy disks, RS-232 serial port, and Centronics parallel printer port. The capabilities of the PSG are controlled through sixteen 8-bit registers. The Sound-Byte program lets you independently and easily manipulate each of the three channels to produce a single sound effect which is played for a time duration you specify. In addition to playing the sound effect, The Sound-Byte will produce complete C source code for a program, which when compiled and linked, will recreate the desired sound effect. This feature can be useful to C-programmers wishing to incorporate "sound-bytes" into their programs for special effects. Sound-Byte supports both High and Medium resolution on the ST. This text file provides instructions for installation and use of The Sound- Byte program. We hope you enjoy the program! Since this product is being distributed as Shareware, you are free to use or distribute it without charge. If you enjoy using The Sound-Byte, and find it particulary useful, we would appreciate hearing from you. Sound-Byte Shareware Contributions made to Structured Technology will be acknowledged with return of technical specifications for our other software products for the ST. Write to us at: Structured Technology P.O. Box 1704 Spring, Texas 77383-1704 =============== GETTING STARTED =============== The following files are included in the SNDBYTE.ARC package: SNDBYTE.PRG: Version 1.00 of the Sound-Byte program. To run the Sound-Byte program, simply double click on this file. This program will support both monochrome (HIGH) and color (MEDIUM) resolution. SNDBYTE.TXT The file you are reading now. ============================ THE SOUND-BYTE CONTROL PANEL ============================ After running The Sound-Byte program (double click on the file SNDBYTE.PRG) you will see the program's main control panel. Most of Sound-Byte's functions are accessed from this panel. Let's take a look at the layout. The control panel contains the following features: o Three (3) control stations, one for each of the three sound channels on the PSG chip (Channel A, B, and C), which are used to set parameters for each sound channel. These control stations are labeled Channel A, Channel B and Channel C. o The lower right corner of the control panel contains six (6) buttons which are used to control the Sound-Byte program functions. These buttons are labeled WAVE, REGS, INFO, CLEAR, PLAY and QUIT. More about these later. o The area immediately below the control station for Channel B contains input devices for the noise period and sound duration measured in milliseconds. o The lower center portion of the control panel contains Sound- Byte's marquis. Clicking on this marquis will activate the program's help facility. To produce a "sound-byte", you use the control stations to set the parameters for each sound channel and then click the PLAY button. The sound-byte is played for a length of time, measured in milliseconds, which you specify in the editable field labeled Sound Duration. Now let's look at actual production of sound effects. The following discussion will describe each feature of The Sound-Byte program. ================ CONTINUOUS TONES ================ Each sound channel control station contains devices which enable you to set channel parameters necessary for the production of sound. To produce a CONTINUOUS TONE on one of the sound channels you must use the following procedure: (1) Enable the channel for tone by selecting the Tone ON button. (2) Set the tone period to determine the pitch of the tone. The tone period is a 12-bit number (0-4095) that determines the pitch of the tone. As the period value increases, the pitch becomes lower in tone. There are several methods to use in setting the period value. The default setting for period values are as follows: Channel A: 478, which corresponds to the note middle C on the chromatic scale. Channel B: 0 Channel C: 0 To change a period setting, you may: o Use the period slider bar. Clicking on the slider bar's left or right arrows moves the period value down or up by an increment of 1. The current period setting is displayed in the indicator box to the immediate right of the period slider bar. Clicking in the period bar moves the period value up or down by an increment of 10. Clicking in the bar to the RIGHT of the slider increments the period value by 10, clicking in the slider bar to the LEFT of the slider decrements the period value by 10. You may also "click and drag" the slider to reposition it in the slider bar. To "click and drag" first click on the slider AND WHILE STILL HOLDING DOWN ON THE LEFT MOUSE BUTTON move the slider to the left or right to reposition, then release the mouse button. The new period value will be computed in accordance with the slider's position in the slider bar. o Click on the period indicator box (the box to the immediate right of the period slider bar which displays the period value) to bring up a selection form for musical notes in the lower, middle and upper octaves of the chromatic scale. To select a note, simply click on the note and the corresponding period value will be returned. Press the CANCEL button to exit the musical note selection screen without adjusting the period value. o Double Click on the period indicator box to bring up a form where you may directly enter the period value. Click on the SET PERIOD button to set the period value entered, or click on CANCEL to exit the form without modifying the current period value. (3) Set the channel volume level by using the Volume slider. The volume for a channel can range from 0-15. A volume of 0 will make the tone inaudible. The default volume level for Channel A is 13. Channels B and C have default values of 0. (4) Specify the sound duration in milliseconds (1 second = 1000 milliseconds) the sound-byte will play by entering a value in the Sound Duration field. The default value is 500 milliseconds (1/2 second). Only positive integer values are supported. You can use the Backspace or Esc keys to clear the Sound Duration field. The duration of the sound must be non-zero to be audible. (5) Click on the PLAY button to play the sound-byte. Tones of the three sound channels may be combined by using the ON and OFF buttons to enable or disable Tone for each channel. Each channel enabled for tone will play during the sound-byte. ================= NOISY PRODUCTIONS ================= Another type of sound can be created by the PSG, namely NOISE! Noise can vary in period from a thin, static-like sound (low periods) to a sound like the rushing wind (high periods). Noise period can vary from a low value of 0 to a high value of 31. To set the noise period, use the slider bar located directly beneath the control station for Channel B. Note that unlike tones, which can have independent period values for each sound channel, all three sound channels use the same period value for noise. The volume of the noise may be independently set for each channel. To make some noise, use the following procedure: (1) Enable the sound channel for noise by selecting the Noise ON button. (2) Set the noise period to determine the pitch of the noise. The noise period is a 5-bit number (0-31) that determines the pitch of the noise. The default setting for noise period is 0. To change the noise period setting, use the Noise Period slider bar. Clicking on the slider bar's left or right arrows moves the period value down or up by an increment of 1. The current period setting is displayed in the indicator box to the immediate right of the period slider bar. (3) Set the channel volume level by using the Volume slider. The volume for a channel can range from 0-15. Remember, a volume of 0 will make the tone inaudible. (4) Specify the duration (in milliseconds) the sound will play by entering a value in the Sound Duration field. The default value is 500 milliseconds (1/2 second). Remember the duration of the sound must be non-zero to be audible. (5) Click on the PLAY button to play the sound-byte. Noises on the three sound channels may be combined by using the ON and OFF buttons to enable or disable Noise for each channel. Each channel enabled for Noise will play during the sound-byte. Both tone and noise may be enabled in a single channel which, when played, produces both types of sound. ================= MAKING SOME WAVES ================= We have just discussed the generation of tone and noise sounds using constant volume. In case you hadn't noticed, we have not yet talked about the Amplitude buttons contained within the confines of each sound channel control station. The amplitude button Const (Constant) has been selected for each sound channel during the previous exercises. It is also possible to create tones and noises using waveform envelopes to vary the volume. A single waveform envelope can be used for all three channels to vary the volume of both tone and noise. Let's take a look. When using waveform envelopes to vary volume, the rate at which the volume changes depends on the shape of the waveform and the waveform period. The waveform period is a 16-bit number, range 0 to 65535. The higher the waveform period, the more slowly the volume level changes. The lower the period, the more quickly the volume level changes. At high periods, TONES created are bell-like, while at lower periods they are very raspy. NOISE created at high waveform periods are percussive like drums or cymbals, while at lower periods sound like the hum of a motor. To use a waveform setting for volume variation, first set the channel tone and/or noise period and volume parameters as discussed above and then use the following procedure: (1) For each sound channel using waveform volume variation, select the Amplitude Wave button. When a waveform is used to vary volume, the volume setting at the control station is ignored, and instead the volume varies between the lowest (0) and highest (15) setting in accordance with the waveform period and shape. To deactivate the waveform volume variation for a channel, select the Const amplitude button at the control station. (2) Click on the WAVE button in the lower right corner of the control panel to activate the waveform selection form. This form is used to collect both the waveform period and waveform shape. Eight (8) waveforms are supported: o Decay and hold. o Attack, sharp decay and hold. o Decay, sharp attack, and decay (reverse saw-tooth wave). o Decay and attack (triangular wave). o Decay, sharp attack and hold. o Attack and decay (triangular wave). o Attack, sharp decay, and attack (saw-tooth wave). o Attack and hold. Select the desired waveform by clicking on the box to the immediate right of the waveform illustration. Only one waveform may be selected. Enter the waveform period (valid range 0-65535) in the editable Waveform Period field. Click on the DONE button when finished to return to the Sound-Byte control panel. Note that tones whose waveform ends in a low, flat line sound only once, while those that stay up or fluctuate sound continuously for the duration of the sound-byte. ===================== PSG REGISTER CONTENTS ===================== You can review the contents of the PSG chip registers by clicking on the control panel's REGS button, thus activating the register contents screen which displays the current contents of the fourteen (14) PSG registers used for sound production. You may also produce the complete C source code for a program which will play the current sound-byte once compiled and linked. To produce the source code, click on the CODE button displayed on the register contents screen. You will be presented with a file selector box where you can enter the name of the file for the C source code. When finished reviewing the register contents, click on the OK button to return to the control panel. The PSG registers contents are described below. Reg 0: Contains the period for the Channel A sound generator. Reg 1: This is a 12-bit number with the low eight bits contained in register 0 and the high 4 bits (high nybble) contained in register 1. The register values are calculated as follows: Register 0 = (12-bit period value) & 0x00FF Register 1 = (12-bit period value >> 8) & 0x000F Reg 2: This register is the same as register 0 except that it affects the period of the Channel B sound generator. Reg 3: This register is the same as register 1 except that it affects the period of the Channel B sound generator. Reg 4: This register is the same as register 0 except that it affects the period of the Channel C sound generator. Reg 5: This register is the same as register 1 except that it affects the period of the Channel C sound generator. Reg 6: This register controls the pitch of the noise generator. Only the low order 5 bits are used. The lower the period, the higher the pitch. Reg 7: This register is the mixer for all the tone and noise generators. The eight bits of this register are defined as follows: Bit 0: Channel A tone generator ON/OFF Bit 1: Channel B tone generator ON/OFF Bit 2: Channel C tone generator ON/OFF Bit 3: Channel A noise generator ON/OFF Bit 4: Channel B noise generator ON/OFF Bit 5: Channel C noise generator ON/OFF Bit 6: Port A I/O select, Input/Output Bit 7: Port B I/O select, Input/Output In the bit settings above, a value of 0 indicates that the channel is on, a value of 1 indicates that the channel is off. The two ports controlled by bits 6 and 7 are not used for sound generation and are masked off and unaffected by The Sound-Byte program. Reg 8: This register controls the amplitude or volume of the Channel A sound generator. The lower 4 bits contain the volume of the channel (0-15). If bit 4 is set, then bits 0-3 are ignored and the loudness will decay (soft to loud or loud to soft) in accordance with the waveform determined by registers 11, 12, and 13. Reg 9: This register is the same as register 8 except that it controls the volume of the Channel B sound generator. Reg 10: This register is the same as register 8 except that it controls the volume of the Channel C sound generator. Reg 11: This registers contains the low byte of the waveform period. Reg 12: This register contains the high byte of the waveform period. Reg 13: This register determines the waveform type. The lower 4 bits are used to select the waveform and have the following meaning: Bit 0: HOLD. If this bit is set, then the tone and the end of the initial decay will be held. Bit 1: ALTERNATE. If this bit is set, then the attack will alternate directions while being repeated. Bit 2: ATTACK. A value of 0 will cause the sound to go from loud to soft (decay), while a value of 1 will cause the sound to go from soft to loud (attack). Bit 3: CONTINUE. If this bit is set then the attack will repeat itself until stopped by another sound. The alternate and hold bits are only valid when this bit is set. Reg 14: This register is used to control port A (not Channel A) of the sound chip and is not used for sound production. This register is not displayed in the Register Contents screen. Reg 15: This register is used to control port B (not Channel B) of the sound chip and is not used for sound production. This register is not displayed in the Register Contents screen. =============== CLEAR THE DECKS =============== Clicking on the control panel's CLEAR button will clear all of the PSG's sound registers (registers 0-13). The two PSG registers which control the chips I/O ports are not used for sound generation and have been masked so as to not be affected by any operation of The Sound-Byte program, including this one. You will be prompted to confirm you selection before the registers are actually cleared. ==================== ABOUT THE SOUND BYTE ==================== Clicking the INFO button on the control panel will display some general information about The Sound-Byte program and Structured Technology, including program version and our address. ================= PLAY IT AGAIN SAM ================= Once you complete parameter setting at the control stations, you can play your sound-byte by clicking on the PLAY button in the lower right corner of the control panel. The sound-byte specified in the PSG registers will be played for the time you indicate in the Sound Duration field. Remember that the duration is specified in milliseconds (1000th's of a second). For example, to set a duration of 1 second, enter 1000 milliseconds in the editable Sound Duration field as: Sound Duration: 1000_ (msec) The actual duration will only approximate your time specification. You can repeat the play of your sound byte as often as desired by simply clicking the PLAY button. ================= GETTING SOME HELP ================= Click on The Sound-Byte marquis to activate the program's help facility. When finished with the help screen, click DONE to return to the program's control panel. Some trouble-shooting tips: If you are not hearing any sound when you click the PLAY button, be sure ..... (1) That either the Tone or Noise ON button is selected for at least one channel. (2) That the volume level for the channel you have enabled is high enough to be audible. Not all volume levels will be audible to all people. (3) That you have set a Tone Period value high enough to be heard. (4) That if you have selected waveform volume variation you have entered an appropriate waveform period and waveform type. (5) That the volume control on your monitor is turned up. (6) If all else fails, check reactions of your spouse, kids or household pets. If they display a mild form of interest in your activity you may need to consult an otolaryngologist. (7) Hint... to help you clearly hear the effects of parameter changes on tone and noise generation, try working with single channel tone and noise effects separately at first to help isolate the sound of the effects. =========== WRAPPING UP =========== To quit The Sound-Byte program, click on the control panel's QUIT button. You will be prompted to confirm your decision. =========================== ABOUT STRUCTURED TECHNOLOGY =========================== Structured Technology consists of a small, but dedicated, group of programmers and professional educators committed to the production of Quality software for the Atari ST/MEGAST line of computers! We are nestled in the piney woods of Spring, Texas and are currently working on some interesting products for the ST. Now Available .... DESK-CALC! The Desk-Calc! is a GEM based scientific calculator with over 65 functions including trigonometric, hyperbolic, traditional math, exponential, logarithmic, power, number manipulation, polar, disk/mouse manipulation functions, collapsible windows and more. The Desk-Calc! has functionality duality. The same file may be used as a desk- accessory or a program. Desk-Calc! supports both monochrome (HIGH) and color (MEDIUM) resolution modes. To order send a check or money order for $12.00 to Structured Technology. A DEMO Version is available on GENIE (DESKCALC.ARC, file #13699). Coming Soon ...... The GEMC+ToolBox The C Programmer's Assistant! (for the Atari ST/MEGA ST line of computers) The GEMC+ToolBox is packaged as an accessory/program and contains a variety of useful features for the C programmer, beginner or advanced. As a desk accessory, GEMC+Toolbox can be used in your favorite GEM editor or GEM programming shell to provide you with "fingertip" access to many reference utilities including a complete on-line description of GEM and standard C language function calls. Some features: * ASCII Reference Table * VDI Function Calls * Hex Keycode Converter * TOS Function Calls * GEM Window Function Calls * ANSI C Function Calls * GEM Menu Function Calls * System Status Info * Escape Sequences * Int Conversion Computer * Printf() Format Characters * Configuration Menu * AES Function Calls * Integrated Help Facility Look for a DEMO Version soon. GEMC+ToolBox technical specifications are currently available by writing Structured Technology. ================================================================= Note: Atari, ST, MEGA, and TOS are trademarks or registered trademarks of Atari Corporation. GEM is a trademark of Digital Research, Inc. =================================================================