SOUND function

Purpose: SOUND is the BCX command to produce a musical tone.

Syntax 1 describes threaded mode or QUEUE mode which runs the sounds in the background on a separate thread.


 Syntax 1:

 RetVal% = Sound(Frequency!, _
                   Duration% _
                 [, Volume%] _
                  [, Voice%] _
                  [, Tempo!])

 Parameters:

  • RetVal% Integer zero if the function succeeds.
  • Frequency! Single precision floating point number in the range which starts at MIDI note 0, C = 8.1758 Hz, and extends to MIDI note 127, G = 12543.875 Hz. See Frequency Note table below for correspondence of Frequency! to 12 tone chromatic scale note.
  • Duration% Integer value representing milliseconds. A Duration% = 1000 would be one second.
  • Volume% [OPTIONAL] Sound volume integer value between 0 and 127. Default and loudest is 127.
  • Voice% [OPTIONAL] integer, default is 0(Acoustic Grand Piano). This integer can have a value between 0 and 127. See table below for descriptions of Voice% options corresponding to the value of the Voice% number.
  • Tempo! [OPTIONAL] Default is 1. Slower is less than 1. 0.5 is half as fast as 1. Faster is greater than 1. 2.0 is twice as fast as 1.

Example: Tugboat Whistle Sound


 $COMPILER "$PELLES$\Bin\pocc -W1 -Gd -Go -Ze -Zx -Tx86-coff $FILE$.c"
 $LINKER "$PELLES$\Bin\polink _
                     -release _
                -machine:ix86 _
           -subsystem:console _
              -OUT:$FILE$.exe _
                   $FILE$.obj "

 SOUND(95, 2000, 127, 111)  ' 2 second blast
 SOUND( 0, 1000,   0, 111)  ' 1 second of silence
 SOUND(95, 2000, 127, 111)  ' 2 second blast
 Sleep(5500)                 ' Give it time to finish

Syntax 2 describes LIVE MODE which plays sounds and waits for sound to finish before releasing control. The syntax difference between this mode and the previous threaded QUEUE mode is that, in LIVE MODE, the Frequency! parameter is used as a LIVE MODE flag by specifying the argument as a negative number. If SOUND is playing in QUEUE Mode, a LIVE MODE call to the SOUND function will end all QUEUE sounds.


 Syntax 2:

 RetVal% = Sound(-Frequency!, _
                    Duration% _
                  [, Volume%] _
                   [, Voice%] _
                   [, Tempo!])

 Parameters:

  • RetVal% Integer zero if the function succeeds.
  • -Frequency! Negative single precision floating point number in the range which starts at -8.1758 and extends to -12543.875. See Frequency Note table below for correspondence of the absolute Frequency! to 12 tone chromatic scale note.
  • Duration% Integer value representing milliseconds. A Duration% = 1000 would be one second.
  • Volume% [OPTIONAL] Sound volume integer value between 0 and 127. Default and loudest is 127.
  • Voice% [OPTIONAL] integer, default is 0(Acoustic Grand Piano). This integer can have a value between 0 and 127. See table below for descriptions of Voice% options corresponding to the value of the Voice% number.
  • Tempo! [OPTIONAL] Default is 1. Slower is less than 1. 0.5 is half as fast as 1. Faster is greater than 1. 2.0 is twice as fast as 1.

Syntax 3 is used to shut down gracefully.


 Syntax 3:

 RetVal% = SOUND(-1)

 Parameters:

  • RetVal% Integer zero if the function succeeds.
  • -1 Set to -1 as flag to shut down gracefully.

Example: The following, SiLlY SyMpHoNy by Kevin Diggins written on August 5th 2003, is a demonstration of LIVE MODE which plays sounds and waits for sound to finish before releasing control.


  $COMPILER "$PELLES$\Bin\pocc -W1 -Gd -Go -Ze -Zx -Tx86-coff $FILE$.c"

  $LINKER "$PELLES$\Bin\polink _
                      -release _
                 -machine:ix86 _
            -subsystem:console _
               -OUT:$FILE$.exe _
                    $FILE$.obj "

  CONST NOTE_LENGTH = 200
 
  RANDOMIZE (TIMER)
 
  DIM RAW Note
 
  PRINT "Press any key to end"
 
  WHILE NOT INSTAT
   Note = 1000*RND
   FOR INTEGER i = 0 to 23 step 2
    SOUND (-Note - i, NOTE_LENGTH, 127, 127 * RND + i) 
   NEXT
  WEND
  
  SOUND (-1)


Syntax 4:

 RetVal% = SOUND(0)

 Parameters:

  • RetVal% Returns the quantity of sounds left in the QUE.
  • 0 Set to zero as flag to return the quantity of sounds left in the QUE.

Syntax 5:

 RetVal% = SOUND(Frequency!,RestDuration)

 Parameters:

  • RetVal% Integer zero if the function succeeds.
  • Frequency! Set to zero(0) as flag for rest.
  • RestDuration Integer specifying number of milliseconds to rest.

Voice Options:


  Voice%  Instrument            Voice%  Instrument

   PIANO                           CHROMATIC PERCUSSION
  0    Acoustic Grand             8   Celesta
  1    Bright Acoustic            9   Glockenspiel
  2    Electric Grand            10   Music Box
  3    Honky-Tonk                11   Vibraphone
  4    Electric Piano 1          12   Marimba
  5    Electric Piano 2          13   Xylophone
  6    Harpsichord               14   Tubular Bells
  7    Clavinet                  15   Dulcimer

    ORGAN                          GUITAR
  16   Drawbar Organ             24   Nylon String Guitar
  17   Percussive Organ          25   Steel String Guitar
  18   Rock Organ                26   Electric Jazz Guitar
  19   Church Organ              27   Electric Clean Guitar
  20   Reed Organ                28   Electric Muted Guitar
  21   Accoridan                 29   Overdriven Guitar
  22   Harmonica                 30   Distortion Guitar
  23   Tango Accordian           31   Guitar Harmonics

    BASS                           SOLO STRINGS
  32   Acoustic Bass             40   Violin
  33   Electric Bass(finger)     41   Viola
  34   Electric Bass(pick)       42   Cello
  35   Fretless Bass             43   Contrabass
  36   Slap Bass 1               44   Tremolo Strings
  37   Slap Bass 2               45   Pizzicato Strings
  38   Synth Bass 1              46   Orchestral Strings
  39   Synth Bass 2              47   Timpani

    ENSEMBLE                       BRASS
  48   String Ensemble 1         56   Trumpet
  49   String Ensemble 2         57   Trombone
  50   SynthStrings 1            58   Tuba
  51   SynthStrings 2            59   Muted Trumpet
  52   Choir Aahs                60   French Horn
  53   Voice Oohs                61   Brass Section
  54   Synth Voice               62   SynthBrass 1
  55   Orchestra Hit             63   SynthBrass 2

    REED                           PIPE
  64   Soprano Sax               72   Piccolo
  65   Alto Sax                  73   Flute
  66   Tenor Sax                 74   Recorder
  67   Baritone Sax              75   Pan Flute
  68   Oboe                      76   Blown Bottle
  69   English Horn              77   Skakuhachi
  70   Bassoon                   78   Whistle
  71   Clarinet                  79   Ocarina

    SYNTH LEAD                     SYNTH PAD
  80   Lead 1(square)           88   Pad 1(new age)
  81   Lead 2(sawtooth)         89   Pad 2(warm)
  82   Lead 3(calliope)         90   Pad 3(polysynth)
  83   Lead 4(chiff)            91   Pad 4(choir)
  84   Lead 5(charang)          92   Pad 5(bowed)
  85   Lead 6(voice)            93   Pad 6(metallic)
  86   Lead 7(fifths)           94   Pad 7(halo)
  87   Lead 8(bass+lead)        95   Pad 8(sweep)

     SYNTH EFFECTS                  ETHNIC
   96  FX 1(rain)               104   Sitar
   97  FX 2(soundtrack)         105   Banjo
   98  FX 3(crystal)            106   Shamisen
   99  FX 4(atmosphere)         107   Koto
  100  FX 5(brightness)         108   Kalimba
  101  FX 6(goblins)            109   Bagpipe
  102  FX 7(echoes)             110   Fiddle
  103  FX 8(sci-fi)             111   Shanai

     PERCUSSIVE                     SOUND EFFECTS
  112  Tinkle Bell               120   Guitar Fret Noise
  113  Agogo                     121   Breath Noise
  114  Steel Drums               122   Seashore
  115  Woodblock                 123   Bird Tweet
  116  Taiko Drum                124   Telephone Ring
  117  Melodic Tom               125   Helicopter
  118  Synth Drum                126   Applause
  119  Reverse Cymbal            127   Gunshot

Frequency Note Table


  Frequency   Note   MIDI#

     8.1758            0
     8.6620            1
     9.1770            2
     9.7227            3
    10.3009            4
    10.9134            5
    11.5623            6
    12.2499            7
    12.9783            8
    13.7500            9
    14.5676           10
    15.4339           11
    16.3516           12
    17.3239           13
    18.3540           14
    19.4454           15
    20.6017           16
    21.8268           17
    23.1247           18
    24.4997           19
    25.9565           20
    27.5000    A0     21
    29.1352    A#0    22
    30.8677    B0     23
    32.7032    C1     24
    34.6478    C#1    25
    36.7081    D1     26
    38.8909    D#1    27
    41.2034    E1     28
    43.6535    F1     29
    46.2493    F#1    30
    48.9994    G1     31
    51.9131    G#1    32
    55.0000    A1     33
    58.2705    A#1    34
    61.7354    B1     35
    65.4064    C2     36
    69.2957    C#2    37
    73.4162    D2     38
    77.7817    D#2    39
    82.4069    E2     40
    87.3071    F2     41
    92.4986    F#2    42
    97.9989    G2     43
   103.8262    G#2    44
   110.0000    A2     45
   116.5409    A#2    46
   123.4708    B2     47
   130.8128    C3     48
   138.5913    C#3    49
   146.8324    D3     50
   155.5635    D#3    51
   164.8138    E3     52
   174.6141    F3     53
   184.9972    F#3    54
   195.9977    G3     55
   207.6523    G#3    56
   220.0000    A3     57
   233.0819    A#3    58
   246.9417    B3     59
   261.6256    C4     60
   277.1826    C#4    61
   293.6648    D4     62
   311.1270    D#4    63
   329.6276    E4     64
   349.2282    F4     65
   369.9944    F#4    66
   391.9954    G4     67
   415.3047    G#4    68
   440.0000    A4     69
   466.1638    A#4    70
   493.8833    B4     71
   523.2511    C5     72
   554.3653    C#5    73
   587.3295    D5     74
   622.2540    D#5    75
   659.2551    E5     76
   698.4565    F5     77
   739.9888    F#5    78
   783.9909    G5     79
   830.6094    G#5    80
   880.0000    A5     81
   932.3275    A#5    82
   987.7666    B5     83
  1046.5023    C6     84
  1108.7305    C#6    85
  1174.6591    D6     86
  1244.5079    D#6    87
  1318.5102    E6     88
  1396.9129    F6     89
  1479.9777    F#6    90
  1567.9817    G6     91
  1661.2188    G#6    92
  1760.0000    A6     93
  1864.6550    A#6    94
  1975.5332    B6     95
  2093.0045    C7     96
  2217.4610    C#7    97
  2349.3181    D7     98
  2489.0159    D#7    99
  2637.0205    E7    100
  2793.8259    F7    101
  2959.9554    F#7   102
  3135.9635    G7    103
  3322.4376    G#7   104
  3520.0000    A7    105
  3729.3101    A#7   106
  3951.0664    B7    107
  4186.0090    C8    108
  4434.9221          109
  4698.6363          110
  4978.0317          111
  5274.0409          112
  5587.6517          113
  5919.9108          114
  6271.9270          115
  6644.8752          116
  7040.0000          117
  7458.6202          118
  7902.1328          119
  8372.0181          120
  8869.8442          121
  9397.2726          122
  9956.0635          123
 10548.0818          124
 11175.3034          125
 11839.8215          126
 12543.8540          127

Example:


 $COMPILER "$PELLES$\Bin\pocc -W1 -Gd -Go -Ze -Zx -Tx86-coff $FILE$.c"
 $LINKER "$PELLES$\Bin\polink _
                       -release _
                  -machine:ix86 _
             -subsystem:windows _
                -OUT:$FILE$.exe _
                     $FILE$.obj "


 GUI "Twinkle"
 
 CONST  IDC_COMBOBOX1 = 101
 CONST  IDC_BUTTON1   = 102
 
 GLOBAL Form1    AS Control
 GLOBAL ComboBox AS Control
 GLOBAL Button1  AS Control
 
 SUB FormLoad
   Form1 = BCX_FORM("Twinkle", 6, 18, 150, 42, _
   DS_MODALFRAME OR WS_POPUP OR WS_CAPTION OR WS_SYSMENU)
   ' *************************************************************************
   ComboBox = BCX_COMBOBOX("", Form1, IDC_COMBOBOX1, 8, 8, 88, 36)
   Button1 = BCX_BUTTON("Play", Form1, IDC_BUTTON1, 112, 8, 32, 14)
   ' *************************************************************************
   FOR INTEGER i = 0 TO 127
     ComboBoxAdd (ComboBox, DATA$[i])
   NEXT
   CENTER (Form1)
   SHOW   (Form1)
 END SUB
 
 BEGIN EVENTS
   IF CBCTL = IDC_BUTTON1 THEN
     PlaySong(CbGetCurSel(ComboBox))
   END IF
   IF CBMSG = WM_CLOSE THEN
     SOUND(0,450,0,8)        ' Silence before leaving
   END IF
 END EVENTS
 
 SUB ComboBoxAdd (hWnd AS HANDLE,A$)
   SendMessage (hWnd,CB_ADDSTRING,0,A$)
 END SUB
 
 FUNCTION CbGetCurSel(hComboBox AS HANDLE)
   FUNCTION = SendMessage(hComboBox,CB_GETCURSEL,0,0)
 END FUNCTION
 
 SUB MidiNote (Note,Length,Voice)        'Lazy Mans Way to get a Note
   FOR INTEGER calcNote = 1 TO 20000
     IF ROUND((LOG(calcNote)-LOG(440))/LOG(2)*12+69,0) = Note THEN
       SOUND(calcNote, Length, 127, Voice)
       EXIT FOR
     END IF
   NEXT
 END SUB
 
 DATA "   0 - Acoustic Grand"
 DATA "   1 - Bright Acoustic"
 DATA "   2 - Electric Grand"
 DATA "   3 - Honky-Tonk"
 DATA "   4 - Electric Piano 1"
 DATA "   5 - Electric Piano 2"
 DATA "   6 - Harpsichord"
 DATA "   7 - Clavinet"
 DATA "   8 - Celesta"
 DATA "   9 - Glockenspiel"
 DATA "  10 - Music Box"
 DATA "  11 - Vibraphone"
 DATA "  12 - Marimba"
 DATA "  13 - Xylophone"
 DATA "  14 - Tubular Bells"
 DATA "  15 - Dulcimer"
 DATA "  16 - Drawbar Organ"
 DATA "  17 - Percussive Organ"
 DATA "  18 - Rock Organ"
 DATA "  19 - Church Organ"
 DATA "  20 - Reed Organ"
 DATA "  21 - Accoridan"
 DATA "  22 - Harmonica"
 DATA "  23 - Tango Accordian"
 DATA "  24 - Acoustic Guitar(nylon)"
 DATA "  25 - Acoustic Guitar(steel)"
 DATA "  26 - Electric Guitar(jazz)"
 DATA "  27 - Electric Guitar(clean)"
 DATA "  28 - Electric Guitar(muted)"
 DATA "  29 - Overdriven Guitar"
 DATA "  30 - Distortion Guitar"
 DATA "  31 - Guitar Harmonics"
 DATA "  32 - Acoustic Bass"
 DATA "  33 - Electric Bass(finger)"
 DATA "  34 - Electric Bass(pick)"
 DATA "  35 - Fretless Bass"
 DATA "  36 - Slap Bass 1"
 DATA "  37 - Slap Bass 2"
 DATA "  38 - Synth Bass 1"
 DATA "  39 - Synth Bass 2"
 DATA "  40 - Violin"
 DATA "  41 - Viola"
 DATA "  42 - Cello"
 DATA "  43 - Contrabass"
 DATA "  44 - Tremolo Strings"
 DATA "  45 - Pizzicato Strings"
 DATA "  46 - Orchestral Strings"
 DATA "  47 - Timpani"
 DATA "  48 - String Ensemble 1"
 DATA "  49 - String Ensemble 2"
 DATA "  50 - SynthStrings 1"
 DATA "  51 - SynthStrings 2"
 DATA "  52 - Choir Aahs"
 DATA "  53 - Voice Oohs"
 DATA "  54 - Synth Voice"
 DATA "  55 - Orchestra Hit"
 DATA "  56 - Trumpet"
 DATA "  57 - Trombone"
 DATA "  58 - Tuba"
 DATA "  59 - Muted Trumpet"
 DATA "  60 - French Horn"
 DATA "  61 - Brass Section"
 DATA "  62 - SynthBrass 1"
 DATA "  63 - SynthBrass 2"
 DATA "  64 - Soprano Sax"
 DATA "  65 - Sax"
 DATA "  66 - Tenor Sax"
 DATA "  67 - Baritone Sax"
 DATA "  68 - Oboe"
 DATA "  69 - English Horn"
 DATA "  70 - Bassoon"
 DATA "  71 - Clarinet"
 DATA "  72 - Piccolo"
 DATA "  73 - Flute"
 DATA "  74 - Recorder"
 DATA "  75 - Pan Flute"
 DATA "  76 - Blown Bottle"
 DATA "  77 - Skakuhachi"
 DATA "  78 - Whistle"
 DATA "  79 - Ocarina"
 DATA "  80 - Lead 1 (square)"
 DATA "  81 - Lead 2 (sawtooth)"
 DATA "  82 - Lead 3 (calliope)"
 DATA "  83 - Lead 4 (chiff)"
 DATA "  84 - Lead 5 (charang)"
 DATA "  85 - Lead 6 (voice)"
 DATA "  86 - Lead 7 (fifths)"
 DATA "  87 - Lead 8 (bass+lead)"
 DATA "  88 - Pad 1 (new age)"
 DATA "  89 - Pad 2 (warm)"
 DATA "  90 - Pad 3 (polysynth)"
 DATA "  91 - Pad 4 (choir)"
 DATA "  92 - Pad 5 (bowed)"
 DATA "  93 - Pad 6 (metallic)"
 DATA "  94 - Pad 7 (halo)"
 DATA "  95 - Pad 8 (sweep)"
 DATA "  96 - FX 1 (rain)"
 DATA "  97 - FX 2 (soundtrack)"
 DATA "  98 - FX 3 (crystal)"
 DATA "  99 - FX 4 (atmosphere)"
 DATA " 100 - FX 5 (brightness)"
 DATA " 101 - FX 6 (goblins)"
 DATA " 102 - FX 7 (echoes)"
 DATA " 103 - FX 8 (sci-fi)"
 DATA " 104 - Sitar"
 DATA " 105 - Banjo"
 DATA " 106 - Shamisen"
 DATA " 107 - Koto"
 DATA " 108 - Kalimba"
 DATA " 109 - Bagpipe"
 DATA " 110 - Fiddle"
 DATA " 111 - Shanai"
 DATA " 112 - Tinkle Bell"
 DATA " 113 - Agogo"
 DATA " 114 - Steel Drums"
 DATA " 115 - Woodblock"
 DATA " 116 - Taiko Drum"
 DATA " 117 - Melodic Tom"
 DATA " 118 - Synth Drum"
 DATA " 119 - Reverse Cymbal"
 DATA " 120 - Guitar Fret Noise"
 DATA " 121 - Breath Noise"
 DATA " 122 - Seashore"
 DATA " 123 - Bird Tweet"
 DATA " 124 - Telephone Ring"
 DATA " 125 - Helicopter"
 DATA " 126 - Applause"
 DATA " 127 - Gunshot"
 
 SUB PlaySong(Voice)
 
   MidiNote(60,450,Voice)
   MidiNote(60,450,Voice)
   MidiNote(67,450,Voice)
   MidiNote(67,450,Voice)
   MidiNote(69,450,Voice)
   MidiNote(69,450,Voice)
   MidiNote(67,999,Voice)
   MidiNote(65,450,Voice)
   MidiNote(65,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(62,450,Voice)
   MidiNote(62,450,Voice)
   MidiNote(60,450,Voice)
 
   SOUND(0,450,0,8)    'Rest!
 
   MidiNote(67,450,Voice)
   MidiNote(67,450,Voice)
   MidiNote(65,450,Voice)
   MidiNote(65,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(62,450,Voice)
 
   SOUND(0,450,0,8)    'Rest!
 
   MidiNote(67,450,Voice)
   MidiNote(67,450,Voice)
   MidiNote(65,450,Voice)
   MidiNote(65,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(62,450,Voice)
 
   SOUND(0,450,0,8)    'Rest!
 
   MidiNote(60,450,Voice)
   MidiNote(60,450,Voice)
   MidiNote(67,450,Voice)
   MidiNote(67,450,Voice)
   MidiNote(69,450,Voice)
   MidiNote(69,450,Voice)
   MidiNote(67,999,Voice)
   MidiNote(65,450,Voice)
   MidiNote(65,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(64,450,Voice)
   MidiNote(62,450,Voice)
   MidiNote(62,450,Voice)
   MidiNote(60,450,Voice)
 
   SOUND(0,450,0,8)    'Rest!
 
 END SUB