Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎


Keyword Abbreviation Token (hex) Version(s) Classification
SOUND S{Shift+O} DA 3.5, 7.0 Command and Statement
DIRECTORY DI{Shift+R} DA 4.x Command and Statement

SOUND voice , frequency , duration [ , [ direction ] [ , [ minFrequency ] [ , [ stepFrequency ] [ , [ waveform ] [ , pulseWidth ] ] ] ] ]
Parameters Type Legal Value(s) Default Value Note(s)
voice Unsigned Byte 1 ~ 3

frequency Unsigned Integer 0 ~ 1023 (v3.5)
0 ~ 65535 (v7.0)
duration Unsigned Integer 0 ~ 65535 (v3.5)
0 ~ 32767 (v7.0) 
  0 will immediately silence the voice
direction Unsigned Byte
  1. Increase and wrap
  2. Decrease and wrap
  3. Increase then Decrease
0 v7.0 only; Irrelevent with default stepFrequency.
minFrequency Unsigned Integer 0 ~ 65535 0 v7.0 only
stepFrequency Unsigned Integer 0 ~ 65535 0 v7.0 only
waveform Unsigned Byte 
  1. Triangle
  2. Sawtooth
  3. Rectangle
  4. Noise
2 v7.0 only
pulseWidth Unsigned Integer 0 ~ 4095 2048 v7.0 only; Applies only to rectangle waveform.
Default makes the rectangle into a square.
Sound generation.  Play one of the sound chip's voices at a given frequency for specific duration.

SOUND allows you to gererate a simple sound effect or play a single note in a musical score.  In order to hear any SOUND, the system volume must be set to a non-zero value (see VOL), and you will need speaker(s) connected to the machine.  In version 7.0, the FILTER may also affect the results of SOUND.
The voice, frequency, and duration parameters are required.  If any of them are missing, or any parameter has an invalid expression, SYNTAX ERROR is generated.  The remaining (optional) parameters are allowed only in BASIC v7.0.  If any parameter is not numeric, TYPE MISMATCH ERROR occurs; a string may converted with VAL.  Floating-point numbers are converted automatically converted with INT.  If the result is not a Legal Value (see table above) then ILLEGAL QUANTITY ERROR occurs.
The TED chip (v3.5) has two identical voices, 1 and 2.  They sound like sawtooth waveform to me.  The final, voice 3, sounds like noise to me.
The SID chip (v7.0) has three identical voices.  Whichever one is used, a choice of waveforms is available.  The default is a rectangular waveform with 50% duty-cycle (explained below).
Each voice is independant, so you can play 1, 2, or all 3 of them at the same time, each with different parameters.  Playing all 3 voices at once with the proper settings will generate a chord.
Frequency controls the pitch of the generated sound.  Unfortunately, frequency, minFrequency, and stepFrequency are not in scientific units of Hertz (Hz), nor common musical notation (like A, A#, B, etc.), but a machine-specific frequency unit.  So not only does the effect of frequency vary between v3.5 and v7.0 (due to different sound chips), but the same version/chip can vary in effect with the same frequency depending on NTSC/PAL standard of the machine.  Note the TED chip (v3.5) has an offset in frequency so that 0 is not zero.  This was surely by design, due to its limited range of frequency values (0 to 1023).

For BASIC 7.0 (the SID chip), the actually frequency produced is either
  • 0.0608 Hz * frequency (on an NTSC machine), or
  • 0.0584 Hz * frequency (on a PAL machine).

Thus a frequency value of 1000 (for example) will produce an audio output of 60.8 Hz on an NTSC machine or 58.4 Hz on a PAL machine.  The maximum fundamental frequency possible (with a value of 65535) is thus either

  • 3.984 kHz (NTSC), or
  • 3.828 kHz (PAL).

This range of frequencies (0 to roughly 4 kHz) is fine for music, but limiting for sound effects.  The SID chip can produce higher frequencies only by indirect methods (mainly, harmonic overtones).  If a high-frequency sound effect is desired, it is useful to apply a high-pass filter to the voice so that the harmonics are emphasized and the fundamental is attenuated.

The duration controls how long the voice will play a sound.  The duration is only partially compatible between v3.5 and v7.0.  Although both are essentially measured in Jiffies, v7.0 limits duration to a smaller range of Legal Values.  This is normally not an issue, because the new lower limit (32767) corresponds to a ridiculously long duration of over 9 minutes!  Unlike the system Jiffy Clock (see TI), which adjusts Jiffy values for NTSC/PAL system timing, SOUND does not adjust duration.  So on an NTSC machine, duration is in "jiffies" (1/60 of a second each) but on PAL systems, duration is really in duo-centi seconds (2/100 or 1/50 of a second each).  Thus a program written on an NTSC machine will play a sound an extra 20% longer when RUN on a PAL machine; a program written on a PAL machine will play a sound 16.6.6% shorter when RUN on an NTSC machine.
Once SOUND starts a voice, it continues with the next statement in the program (if any).  After the specified duration, BASIC will silence the voice no matter where in the program BASIC might be.  If a program ends with SOUND playing, it will also continue in direct mode for the specified duration.  Each voice can only play one SOUND at a time.  If the specified voice is currently/already playing when another SOUND statement is executed, BASIC will wait for the previous SOUND to finish before it executes the new one.  There is one exception: if the duration is zero then SOUND will immediately silence the voice.
The direction, minFrequency, and stepFrequency are mainly used for generating sound effects, as opposed to playing a musical note.  However with the proper values it might be useful for playing a note with a trill or mordent.  In short, these parameters cause the voice to modulate its frequency while playing.  For this to work at all, the stepFrequency must be a non-zero value.  Because zero is the default, it really should come before direction and minFrequency in the Syntax!  In addition, the minFrequency (using the same units as frequency) must be different than the frequency.  The minFrequency has a default of zero which is useful for some sound effects, but for other sound effects, and especially for musical notes, you will probably want its value closer to frequency.
When SOUND starts the voice it begins with the indicated frequency (which we'll see is also the maxFrequency).  Then each IRQ (occurs 60 or 50 times per second for NTSC and PAL respectively) the frequency is adjusted by stepFrequency: if the direction is 0 then the frequency will be increased until it excedes the maxFrequency at which point it will reset (wrap-around) to the minFrequency; if the direction is 1 then the frequency is decreased until it precedes the minFrequency at which point it will reset (wrap-around) to maxFrequency; finally, if the direction is 2 then the frequency is first increased (like when direction is 0) but when the maxFrequency is reached, the frequency begins decreasing (like when direction is 1), and when frequency reaches the minFrequency it will start over by increasing frequency again (in other words, the frequency will "smoothly" oscillate between minFrequency and maxFrequency without the harsh wrap-around).  A direction of 2 is usually what you want for a trill or mordent; however if the stepFrequency is very small (releative to the duration) then direction 1 might work too.
The stepFrequency should be smaller than half the difference between (max)frequency and minFrequency, although BASIC does not require this.  If not, the effects of direction just described may seem reversed.  I like to think of this phenomenon as delta-frequency aliasing (don't know what, if any, is the correct term), but it is the audio equivalant of Moiré patterns in images.
* TO DO * Describe what happens when minFrequency is greater than (max)frequency.
The next to last parameter, waveform, controls the timbre of the sound, just like a "C" played on piano will sound different than a "C" played on a guitar.  A value of 0 produces a triangle waveform which is a poor digital imitation of a sine wave, and sounds similar to some wind instruments, like flutes.  A value of 1 produces a sawtooth waveform and sounds like some brass instruments, like trumpets.  A value of 2 produces a rectangular waveform and is quite versatile because you can control its duty-cycle (described below).  Finally a value of 3 produces a noise waveform which is mostly useful for sound effects like ocean waves and explosions, but might be useful for a precussion instrument like a snare drum.
If a rectangular waveform is selected (the default), the final parameter, pulseWidth species the duty-cycle by this equation: dutyCycle = 100% * pulseWidth / 4096.  The default pulseWidth of 2048 thus produces a 50% duty-cycle which is a special case of the rectangular waveform known as a square wave.  Using different values for pulseWidth allows a nice variety of sound timbres.  At 50% the sound quality is at its "fullest" sounding like some cross between a stringed instrument and a horn... the classic digital synthesizer sound.  As the duty-cycle moves away from 50%, the sound quality becomes more "reedy" and softer.  You will hear nothing when the duty-cycle reaches 0% or 100%.  Values below 50% sound the same as their "complement" above 50%; so a 40% duty-cycle sounds the same as 60% duty-cycle (they are both 10% away from 50%).  This is because the human ear is indifferent to phase modulation (a 40% duty-cycle waveform is a 180-degree phase-shifted version of a 60% duty-cycle waveform).
The SOUND statement does not allow you to control the amplitude or loudness of the voice.  All voices play at the same amplitude specified by the master volume.  Hardware note: in v7.0, the voice of the SID chip is played using attack, decay, and release parameters of maximum speed (0 value) and a sustain parameter of maximum amplitude (15 value).
Because of the NTSC/PAL differences in the frequency parameter, and the lack of volume control of each voice, you may find the PLAY command to be useful.  Although it is designed for playing musical scores and not sound effects; with that command you can't create frequency sweeps like you can using the direction parameter of SOUND.
Examples (v3.5):
SOUND 1,1000,55 : REM high-pitch "triangle" beep, about 1 second

SOUND 3,1000,55 : REM high-pitch "noise" sound, about 1 second

SOUND 1,200,6000 : REM low-pitched "triangle" beep, about 100 seconds

SOUND 1,200,0 : REM silence that annoying sound! (frequency doesn't matter)

Examples (v7.0):
SOUND 1,1000,55 : REM low-pitch square wave, about 1 second
SOUND 1,61000,55 : REM high-pitch square wave, about 1 second
SOUND 1,9000,55,,,10 : REM mid-pitch square wave, about 1 second, slow rising step
SOUND 1,9000,55,,,90 : REM mid-pitch square wave, about 1 second, fast rising step
SOUND 1,9000,55,1,,10 : REM mid-pitch square wave, about 1 sec., slow falling step
SOUND 1,9000,55,1,,90 : REM mid-pitch square wave, about 1 sec., fast falling step
SOUND 1,9000,55,2,,500 : REM mid-pitch square wave, ~ 1 second, rise-fall-rise...
SOUND 1,9000,55,,,,0 : REM mid-pitch triangle wave, about 1 second
SOUND 1,9000,55,,,,1 : REM mid-pitch sawtooth wave, about 1 second
SOUND 1,9000,55,,,,3 : REM mid-pitch noise wave, about 1 second
SOUND 1,9000,55,,,,2 : REM mid-pitch rectangle wave, 50% duty-cycle (square)
SOUND 1,9000,55,,,,2,2048 : REM same as previous
SOUND 1,9000,55,,,,2,1024 : REM mid-pitch rectangle wave, 25% duty-cycle
SOUND 1,9000,55,,,,2, 409 : REM mid-pitch rectangle wave, 10% duty-cycle
  Compare With  
  Contrast With  
  See Also  

© H2Obsession, 2014, 2017