EzMIDI32: Difference between revisions

From Moonlight Design
Jump to navigation Jump to search
(New page: EzMIDI32, also known as EasyMIDI32, is a {{Tech:MIDI}} library and thin wrapper around [http://en.wikipedia.org/wiki/Win32_console Microsoft's console API]. This library was primarily writ...)
 
No edit summary
 
Line 1: Line 1:
EzMIDI32, also known as EasyMIDI32, is a {{Tech:MIDI}} library and thin wrapper around [http://en.wikipedia.org/wiki/Win32_console Microsoft's console API]. This library was primarily written for the annual [http://en.wikipedia.org/wiki/Christmas_song December holiday song] mid-year project for first-year computer science students at [http://www.gcisd-ghs.org/ Grapevine High School]. This was a follow-up project to [[ScreenWindow]] after the course moved from {{Tech:Pascal}} to {{Tech:C++}}.
EzMIDI32, also known as EasyMIDI32, is a {{Tech:MIDI}} library and thin wrapper around [http://en.wikipedia.org/wiki/Win32_console Microsoft's console API]. This library was primarily written for the annual [http://en.wikipedia.org/wiki/Christmas_song December holiday song] mid-year project for first-year computer science students at [http://www.gcisd-ghs.org/ Grapevine High School]. This was a follow-up project to [[ScreenWindow]] after the course moved from {{Tech:Pascal}} to {{Tech:C++}}.
==Download==
*'''[https://www.moonlightdesign.org/steve/programs/ezmidi32.exe Download EzMIDI32]'''
*{{CatSetupFiles}}
==Documentation==
The following is the readme.txt file that gets installed with the full distribution:
<pre>
EasyMIDI32 was designed and programmed by Steven Lawrance
and is (c) 1996, 1998 Steven Lawrance.
This version is 2.02.98.1 (Release 2)
The 16-bit version can be found on the Lawrance Consulting
web site.  Details are at the bottom of this document.
If you have release 1 of the ScreenWindow API, you must
download release 2 to use midiGetHMidiOut and instrument
number 128.
=========================================
TABLE OF CONTENTS
=========================================
1.  MIDI Functions
2.  Console Functions
A.  General MIDI Instruments
=========================================
1.  MIDI Functions
=========================================
The MIDI functions implemented by EzMIDI32.DLL allow anyone to
easily access the basic MIDI capabilities of supportive
computers.  The Win32 API currently requires programmers to
have technical background on the MIDI specification, but for
those who simply want to turn notes on and off, EzMIDI32
allows easy access without requiring deep technical knowledge.
These functions are safe for use in both single-threaded and
multithreaded applications.  If used in an application with
an active console, program breaks automatically clean up
the MIDI interface before closing the program.
Functions:
BOOL midiInitialize();
BOOL midiNoteOn(int channel, int note, int pressure);
BOOL midiNoteOff(int channel, int note, int velocity);
BOOL midiInstrument(int channel, int instrument);
BOOL midiHoldPedal(int channel, BOOL hold);
BOOL midiWait(UINT ms);
HMIDIOUT midiGetHMidiOut();
BOOL midiUninitialize();
-----------------------------------------
midiInitialize
-----------------------------------------
Initializes the EasyMIDI interface and opens the MIDI output
port internally.
BOOL midiInitialize();
Parameters:
  none
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDIALREADYOPEN      EasyMIDI already initialized
  ERROR_MIDIOPEN            The MIDI output port is in use by
                            another process
  ERROR_NOMIDI              System does not have any MIDI
                            output devices installed
Remarks:
  Call this function before you use any other EasyMIDI functions.
  Failure to do so will cause the other functions to return zero
  until midiInitialize succeeds.
  If your application has an open console, program break messages
  are handled by EasyMidi to allow proper cleanup of the MIDI
  interface.  This special handling can be disabled by not having
  an open console before calling midiInitialize.  Calling
  midiUninitialize will remove EasyMidi's special break handling
  function from the console.
See Also:
  midiOutOpen
-----------------------------------------
midiNoteOn
-----------------------------------------
Sends a MIDI message to turn on a note on a given channel with
a given pressure.
BOOL midiNoteOn(int channel, int note, int pressure);
Parameters:
  int channel                The MIDI channel to send the message
                            on.  Valid values: 0..127
  int note                  The note number to play.  See the
                            remarks for more information on notes
  int pressure              The pressure to apply to the note.
                            Higher numbers result in louder
                            intensities.  Valid values: 0..127
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL      The channel parameter is invalid
  ERROR_BADMIDINOTE          The note parameter is invalid
  ERROR_BADMIDIPRESSURE      The pressure parameter is invalid
  ERROR_MIDISEND            Writing to the MIDI output port
                            failed
Remarks:
  When a note is turned on, it will remain on until it is turned
  off with either midiNoteOff or midiOutReset.  Channels allow
  songs to play notes of different instruments simultaneously.
  Valid note values range from zero to 127.  Middle C has a value
  of 60.  The length of an octave is 12, meaning that the value
  of C above Middle C is 72.  A note's sharp has the same value
  as the next note's flat.
See Also:
  midiNoteOff, midiWait, midiOutReset, midiOutShortMsg
-----------------------------------------
midiNoteOff
-----------------------------------------
Sends a MIDI message to turn off a note on a given channel at a
given velocity.
BOOL midiNoteOff(int channel, int note, int velocity);
Parameters:
  int channel                The MIDI channel to send the message
                            on.  Valid values: 0..127
  int note                  The note number to stop.  See the
                            remarks for more information on notes
  int velocity              How fast a note should stop.  Lower
                            values cause the note to fade longer,
                            and higher values make the stop more
                            abruptly.  Valid values: 0..127
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL      The channel parameter is invalid
  ERROR_BADMIDINOTE          The note parameter is invalid
  ERROR_BADMIDIVELOCITY      The velocity parameter is invalid
  ERROR_MIDISEND            Writing to the MIDI output port
                            failed
Remarks:
  Notes that are turned off with this function must have
  previously been turned on with midiNoteOn.  To create a delay
  between midiNoteOn and midiNoteOff calls, either use
  midiWait or some other delay code.
  If more than one note was turned on in the same channel, you
  still need to turn off each note if you want to make the channel
  silent.  That is, you must have a midiNoteOff call for every
  midiNoteOn call if you want to have a song that does not have
  any notes still on when it is done.  Even if the multiple notes
  in the same channel had the same note value (such as an
  orchestra effect), you still need to call midiNoteOff for every
  call to midiNoteOn.
  If midiHoldPedal is set on the same channel passed to this
  function, the note will not be turned off until midiHoldPedal
  is called with FALSE.  But if you unset midiHoldPedal without
  calling midiNoteOff, the note will continue to play until
  midiNoteOff is called on that note.
  Some instruments have longer play durations than others, and
  in some cases the note may already seem to be "off" when
  internally it is on.  Or, if a note is turned off before the
  entire note has been played, then the user will not hear the
  part of the note that normally comes after the point where
  the note was turned off.  Many notes repeat during longer
  play durations and will play for the entire time the note
  is on regardless of length, such as a violin.  A piano,
  however, does not repeat in most cases.
See Also:
  midiNoteOn, midiWait, midiOutReset, midiOutShortMsg
-----------------------------------------
midiInstrument
-----------------------------------------
Sets the instrument that new notes will use in the given channel.
BOOL midiInstrument(int channel, int instrument);
Parameters:
  int channel                The MIDI channel to send the message
                            on.  Valid values: 0..127
  int instrument            The instrument to use.  Read through
                            Appendix A for more information on
                            instruments.  Valid values: 0..128
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL      The channel parameter is invalid
  ERROR_BADMIDIINSTRUMENT    The instrument parameter is invalid
  ERROR_MIDISEND            Writing to the MIDI output port
                            failed
Remarks:
  This function allows you to set the instrument that the next
  note on the given channel, if any, will use.  Use midiNoteOn
  to turn on a note after calling midiInstrument to use the
  new instrument.
  See Appendix A for more information on using instruments and
  for the valid values.
See Also:
  midiNoteOn, midiNoteOff, midiOutShortMsg
-----------------------------------------
midiHoldPedal
-----------------------------------------
Postpones midiNoteOff messages on the given channel until
midiHoldPedal is called again.
BOOL midiHoldPedal(int channel, BOOL hold);
Parameters:
  int channel                The MIDI channel to send the message
                            on.  Valid values: 0..127
  int hold                  If TRUE, midiNoteOff messages are
                            postponed until midiHoldPedal is
                            called with FALSE in the hold
                            parameter.  If FALSE, any holds on
                            the given MIDI channel are released
                            and all waiting MIDI note off messages
                            are processed at the same time
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL      The channel parameter is invalid
  ERROR_MIDISEND            Writing to the MIDI output port
                            failed
Remarks:
  This function delays MIDI note off messages in the MIDI
  processor until this function is called again to un-hold the
  messages.  The delay is implemented by the MIDI hardware and
  might not be supported by some MIDI devices.  This function's
  capabilities can be duplicated by moving all the midiNoteOff
  calls into one place where they are all called at once.
See Also:
  midiNoteOff, midiOutShortMsg
-----------------------------------------
midiWait
-----------------------------------------
Causes the current thread to do nothing for the given number of
milliseconds.  The Win16 version continually yields the processor
to other tasks until the given number of milliseconds has
elapsed.
BOOL midiWait(UINT ms);
Parameters:
  UINT ms                    An unsigned integer for the number
                            of milliseconds the delay should
                            last.
Return Values:
  Returns a non-zero value if the function was successful.  The
  Win16 version always returns non-zero.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
Remarks:
  In the Win32 version, a zero value for ms will cause EasyMIDI
  to forfeit the remainder of its timeslice to other programs of
  the same priority.  In that case, the function will return
  almost immediately after a very brief delay, if any.  The Win16
  version always returns immediately when ms is zero.
See Also:
  Sleep (Win32 version); Yield, timeGetTime (Win16 version)
-----------------------------------------
midiGetHMidiOut
-----------------------------------------
Returns the HMIDIOUT handle that was opened when midiInitialize
was successfully called.  If midiInitialize failed or was not
called, then the returned value is not a valid HMIDIOUT handle.
HMIDIOUT midiGetHMidiOut();
Parameters:
  none
Return Values:
  The internal hMidiOut variable is always returned, regardless
  of its validity.
Remarks:
  Use this function if you want to call midiOutxxxx API functions
  manually.  When using the value returned from this function,
  avoid calling midiOutOpen and midiOutClose.  To close the
  handle, use EasyMIDI's midiUninitialize.
  Known functions that can be used with the value returned by
  this function include midiConnect, midiDisconnect,
  midiOutCacheDrumPatches, midiOutCachePatches, midiOutGetDevCaps,
  midiOutGetID, midiOutGetNumDevs, midiOutGetVolume,
  midiOutLongMsg, midiOutMessage, midiOutPrepareHeader,
  midiOutReset, midiOutSetVolume, midiOutShortMsg, and
  midiOutUnprepareHeader.
See Also:
  midiInitialize, midiUninitialize
-----------------------------------------
midiUninitialize
-----------------------------------------
Silences any playing notes and closes the MIDI output device.
BOOL midiUninitialize();
Parameters:
  none
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
Remarks:
  This function calls midiOutReset before closing the MIDI output
  port.  Internal variables are freed at this time too, and the
  special handling for program break codes on the console, if
  installed, is removed.  Call this function when you are
  finished with EasyMIDI at the end of your program.
See Also:
  midiInitialize, midiOutReset, midiOutClose
=========================================
2.  Console Functions
=========================================
The console functions, only available in the Win32 version
of EasyMIDI, allow programs to use a standard Win32 console
to produce colorful output without requiring standard
libraries to implement textcolor and textbackground.
Besides, their implementations do not work in the libraries
that were tested so far.
These functions are safe for use in both single-threaded and
multithreaded applications.  If used in an application with
an active console, program breaks automatically clean up
the MIDI interface before closing the program.
Functions:
BOOL SetFgColor(int newcolor);
BOOL SetBgColor(int newcolor);
BOOL ClearScreen(void);
BOOL GotoXY(short x, short y);
DWORD WhereX(void);
DWORD WhereY(void);
BOOL Write(LPCTSTR lpszString);
Compatibility Functions:
#define gotoxy(x, y) GotoXY(x, y)
#define clrscr() ClearScreen()
#define textcolor(mode) SetFgColor(mode)
#define textbackground(mode) SetBgColor(mode)
#define wherex() WhereX()
#define wherey() WhereY()
-----------------------------------------
SetFgColor
-----------------------------------------
Sets the current foreground color on the console window that
was available when midiInitialize was called, if any.
BOOL SetFgColor(int newcolor);
#define textcolor(mode) SetFgColor(mode)
Parameters:
  int newcolor              A value for the new color.  Valid
                            values range from 0 to 15, and
                            can be one of the following:
                            BLACK, BLUE, GREEN, CYAN, RED,
                            MAGENTA, BROWN, LIGHTGRAY, DARKGRAY,
                            LIGHTBLUE, LIGHTGREEN, LIGHTCYAN,
                            LIGHTRED, LIGHTMAGENTA, YELLOW, and
                            WHITE
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                            midiInitialize was called
  Other values              Refer to the documentation for
                            the SetConsoleTextAttribute Win32
                            API function
Remarks:
  This function is only implemented in the Win16 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call textcolor(newcolor).
  In the Win32 version, BROWN's displayed color might look more
  like a dark yellow than anything while in window mode.
  Switching to full screen mode typically solves this problem.
  If using Win16, ScreenWindow properly initializes a color
  palette with a realistic brown.
See Also:
  textcolor, midiInitialize
-----------------------------------------
SetBgColor
-----------------------------------------
Sets the current background color on the console window that
was available when midiInitialize was called, if any.
BOOL SetBgColor(int newcolor);
#define textbackground(mode) SetBgColor(mode)
Parameters:
  int newcolor              A value for the new color.  Valid
                            values range from 0 to 15, and
                            can be one of the following:
                            BLACK, BLUE, GREEN, CYAN, RED,
                            MAGENTA, BROWN, LIGHTGRAY, DARKGRAY,
                            LIGHTBLUE, LIGHTGREEN, LIGHTCYAN,
                            LIGHTRED, LIGHTMAGENTA, YELLOW, and
                            WHITE
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                            midiInitialize was called
  Other values              Refer to the documentation for
                            the SetConsoleTextAttribute Win32
                            API function
Remarks:
  This function is only implemented in the Win16 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call textbackground(newcolor).
  Some video cards might not support background colors after
  LIGHTGRAY while in full screen text mode.  Switching to window
  mode should correct this problem.
  In the Win32 version, BROWN's displayed color might look more
  like a dark yellow than anything while in window mode.
  Switching to full screen mode typically solves this problem.
  If using Win16, ScreenWindow properly initializes a color
  palette with a realistic brown.
See Also:
  textbackground, midiInitialize
-----------------------------------------
ClearScreen
-----------------------------------------
Clears the screen and positions the cursor at the top-left corner
of the console.
BOOL ClearScreen(void);
#define clrscr() ClearScreen()
Parameters:
  none
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                            midiInitialize was called
  Other values              Refer to the documentation for
                            the SetConsoleOutputAttribute,
                            FillConsoleOutputCharacter, and
                            SetConsoleCursorPosition Win32
                            API functions
Remarks:
  The screen clears with the current background color.
  This function is only implemented in the Win16 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call clrscr().
  Some video cards might not support background colors after
  LIGHTGRAY while in full screen text mode.  Switching to window
  mode should correct this problem.
  In the Win32 version, BROWN's displayed color might look more
  like a dark yellow than anything while in window mode.
  Switching to full screen mode typically solves this problem.
  If using Win16, ScreenWindow properly initializes a color
  palette with a realistic brown.
See Also:
  clrscr, midiInitialize
-----------------------------------------
GotoXY
-----------------------------------------
Positions the cursor at the given (x,y) coordinates.
BOOL GotoXY(short x, short y);
#define gotoxy(x, y) GotoXY(x, y)
Parameters:
  short x                    The column to move to
  short y                    The row to move to
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                            midiInitialize was called
  Other values              Refer to the documentation for
                            the SetConsoleCursorPosition
                            Win32 API function
Remarks:
  This function is only implemented in the Win32 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call gotoxy(x, y).
See Also:
  gotoxy, midiInitialize
-----------------------------------------
WhereX
-----------------------------------------
Returns the current column of the cursor in the console window.
DWORD WhereX(void);
#define wherex() WhereX()
Parameters:
  none
Return Values:
  Returns a non-zero value equaling the current column in the console
  window if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                            midiInitialize was called
  Other values              Refer to the documentation for
                            the GetConsoleScreenBufferInfo
                            Win32 API function
Remarks:
  This function is only implemented in the second release of the
  Win32 version of EasyMIDI.  Programmers using the 16-bit version
  should use the ScreenWindow library and call wherex(x, y).
See Also:
  wherey, midiInitialize
-----------------------------------------
WhereY
-----------------------------------------
Returns the current row of the cursor in the console window.
DWORD WhereY(void);
#define wherey() WhereY()
Parameters:
  none
Return Values:
  Returns a non-zero value equaling the current row in the console
  window if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                            midiInitialize was called
  Other values              Refer to the documentation for
                            the GetConsoleScreenBufferInfo
                            Win32 API function
Remarks:
  This function is only implemented in the second release of the
  Win32 version of EasyMIDI.  Programmers using the 16-bit version
  should use the ScreenWindow library and call wherey(x, y).
See Also:
  wherex, midiInitialize
-----------------------------------------
Write
-----------------------------------------
Prints text onto the console at the current cursor
position.
BOOL Write(LPCTSTR lpszString);
Parameters:
  LPCTSTR lpszString        Long pointer to a constant
                            Unicode(tm) or ASCII string
                            to print on the console
Return Values:
  Returns a non-zero value if the function was successful.
  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):
  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                            midiInitialize was called
Remarks:
  This function allows Unicode strings to print when using a
  Unicode-enabled version of Win32.  Windows NT and Windows CE
  both support Unicode internally on all Win32 API functions;
  Win95 and Win98 do not.
  On Win95 consoles, writing a newline may cause the remainder
  of the line, if any, to instantly take on the current
  foreground and background colors.  If this effect is not
  desired, then use GotoXY to manually move to the next line.
  This problem is not an issue with Windows NT unless if you
  are writing to the last row of the console.  Standard library
  implementations from both Microsoft and Borland also call
  WriteConsole and/or WriteFile, and this effect is duplicated.
  It is just as safe to call Write as it is to call standard
  library output and input functions.  If cout, printf, puts,
  etc. are used, the effects are the same (e.g., the text is
  written to the screen using the current colors and position).
See Also:
  GotoXY, cout, printf, puts, midiInitialize
=========================================
A.  General MIDI Instruments
=========================================
In MIDI, instruments are referenced by a 8-bit unsigned integer,
ranging from 0 to 128 (129-255 are invalid MIDI instruments).
The following instruments have been grouped for easy reference
by category (Pianos, Chromatic Percussion, Organs, Guitars,
Bass, Strings, Ensembles, Brass, Reeds, Pipes, Synth Lead,
Synth Pad, Background Tracks, Miscellaneous Strings,
Miscellaneous Percussion, Sound Effects, and Standard
Percussion).
-----------------------------------------
Pianos
-----------------------------------------
0  Acoustic grand piano
1  Bright acoustic piano
2  Electric grand piano
3  Honky-tonk piano
4  Rhodes piano
5  Chorused piano
6  Harpsichord
7  Clavinet
-----------------------------------------
Chromatic Percussion
-----------------------------------------
8  Celesta
9  Glockenspiel
10  Music box
11  Vibraphone
12  Marimba
13  Xylophone
14  Tubular bells
15  Dulcimer
-----------------------------------------
Organs
-----------------------------------------
16  Hammond organ
17  Percussive organ
18  Rock organ
19  Church organ
20  Reed organ
21  Accordion
22  Harmonica
23  Tango accordion
-----------------------------------------
Guitars
-----------------------------------------
24  Acoustic guitar (nylon)
25  Acoustic guitar (steel)
26  Electric guitar (jazz)
27  Electric guitar (clean)
28  Electric guitar (muted)
29  Overdriven guitar
30  Distortion guitar
31  Guitar harmonics
-----------------------------------------
Bass
-----------------------------------------
32  Acoustic bass
33  Electric bass (finger)
34  Electric bass (pick)
35  Fretless bass
36  Slap bass 1
37  Slap bass 2
38  Synth bass 1
39  Synth bass 2
-----------------------------------------
Strings
-----------------------------------------
40  Violin
41  Viola
42  Cello
43  Contrabass
44  Tremolo strings
45  Pizzicato strings
46  Orchestral harp
47  Timpani
-----------------------------------------
Ensembles
-----------------------------------------
48  String ensemble 1
49  String ensemble 2
50  Synth. strings 1
51  Synth. strings 2
52  Choir Aahs
53  Voice Oohs
54  Synth voice
55  Orchestra hit
-----------------------------------------
Brass
-----------------------------------------
56  Trumpet
57  Trombone
58  Tuba
59  Muted trumpet
60  French horn
61  Brass section
62  Synth. brass 1
63  Synth. brass 2
-----------------------------------------
Reeds
-----------------------------------------
64  Soprano sax
65  Alto sax
66  Tenor sax
67  Baritone sax
68  Oboe
69  English horn
70  Bassoon
71  Clarinet
-----------------------------------------
Pipes
-----------------------------------------
72  Piccolo
73  Flute
74  Recorder
75  Pan flute
76  Bottle blow
77  Shakuhachi
78  Whistle
79  Ocarina
-----------------------------------------
Synth Lead
-----------------------------------------
80  Lead 1 (square)
81  Lead 2 (sawtooth)
82  Lead 3 (calliope lead)
83  Lead 4 (chiff lead)
84  Lead 5 (charang)
85  Lead 6 (voice)
86  Lead 7 (fifths)
87  Lead 8 (brass + lead)
-----------------------------------------
Synth Pad
-----------------------------------------
88  Pad 1 (new age)
89  Pad 2 (warm)
90  Pad 3 (polysynth)
91  Pad 4 (choir)
92  Pad 5 (bowed)
93  Pad 6 (metallic)
94  Pad 7 (halo)
95  Pad 8 (sweep)
-----------------------------------------
Background Tracks
-----------------------------------------
96  Ice Rain
97  Soundtrack
98  Crystal
99  Atmosphere
100 Brightness
101 Goblin
102 Echo Drops
103 Star Theme
-----------------------------------------
Miscellaneous Strings
-----------------------------------------
104 Sitar
105 Banjo
106 Shamisen
107 Koto
108 Kalimba
109 Bagpipe
110 Fiddle
111 Shenai
-----------------------------------------
Miscellaneous Percussion
-----------------------------------------
112 Tinker Bell
113 Agogo
114 Steel Drum
115 Wood Block
116 Taiko Drum
117 Melodic Tom
118 Synth Drum
119 Reverse Cymbal
-----------------------------------------
Sound Effects
-----------------------------------------
120 Guitar fret noise
121 Breath noise
122 Seashore
123 Bird tweet
124 Telephone ring
125 Helicopter
126 Applause
127 Gunshot
-----------------------------------------
Standard Percussion (Instrument 128)
-----------------------------------------
The values listed are the note numbers to
use for the given sound on instrument 128:
35 Acoustic Bass Drum
36 Bass Drum 1
37 Side Stick
38 Acoustic Snare
39 Hand Clap
40 Electric Snare
41 Low Floor Tom
42 Closed High-Hat
43 High Floor Ton
44 Pedal High-Hat
45 Low Tom
46 Open High-Hat
47 Low-Mid Tom
48 High-Mid Tom
49 Crash Cymbal 1
50 High Tom
51 Ride Cymbal 1
52 Chinese Cymbal
53 Ride Bell
54 Tambourine
55 Splash Cymbal
56 Cowbell
57 Crash Cymbal 2
58 Vibraslap
59 Ride Cymbal 2
60 High Bongo
61 Low Bongo
62 Mute High Conga
63 Open High Conga
64 Low Conga
65 High Timbale
66 Low Timbale
67 High Agogo
68 Low Agogo
69 Cabasa
70 Maracas
71 Short Whistle
72 Long Whistle
73 Short Guiro
74 Long Guiro
75 Claves
76 High Wood Block
77 Low Wood Block
78 Mute Cuica
79 Open Cuica
80 Mute Triangle
81 Open Triangle
=========================================
Written by Steven Lawrance on 8-20-1998
Revised on 12-2-1998 by Steven Lawrance for Release 2
Portions copied from the Microsoft Platform SDK reference
on MIDI instruments, and from Creative Labs's AWE Control
Panel v2.07.0.  This document is for educational use only.
All trademarks belong to their respective owners.
</pre>

Latest revision as of 23:17, 14 October 2007

EzMIDI32, also known as EasyMIDI32, is a MIDI library and thin wrapper around Microsoft's console API. This library was primarily written for the annual December holiday song mid-year project for first-year computer science students at Grapevine High School. This was a follow-up project to ScreenWindow after the course moved from Pascal to C++.

Download

Documentation

The following is the readme.txt file that gets installed with the full distribution:

EasyMIDI32 was designed and programmed by Steven Lawrance
and is (c) 1996, 1998 Steven Lawrance.

This version is 2.02.98.1 (Release 2)

The 16-bit version can be found on the Lawrance Consulting
web site.  Details are at the bottom of this document.

If you have release 1 of the ScreenWindow API, you must
download release 2 to use midiGetHMidiOut and instrument
number 128.

=========================================
TABLE OF CONTENTS
=========================================

1.  MIDI Functions
2.  Console Functions
A.  General MIDI Instruments


=========================================
1.  MIDI Functions
=========================================

The MIDI functions implemented by EzMIDI32.DLL allow anyone to
easily access the basic MIDI capabilities of supportive
computers.  The Win32 API currently requires programmers to
have technical background on the MIDI specification, but for
those who simply want to turn notes on and off, EzMIDI32
allows easy access without requiring deep technical knowledge.

These functions are safe for use in both single-threaded and
multithreaded applications.  If used in an application with
an active console, program breaks automatically clean up
the MIDI interface before closing the program.

Functions:
BOOL midiInitialize();
BOOL midiNoteOn(int channel, int note, int pressure);
BOOL midiNoteOff(int channel, int note, int velocity);
BOOL midiInstrument(int channel, int instrument);
BOOL midiHoldPedal(int channel, BOOL hold);
BOOL midiWait(UINT ms);
HMIDIOUT midiGetHMidiOut();
BOOL midiUninitialize();


-----------------------------------------
midiInitialize
-----------------------------------------

Initializes the EasyMIDI interface and opens the MIDI output
port internally.

BOOL midiInitialize();

Parameters:
  none

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDIALREADYOPEN      EasyMIDI already initialized
  ERROR_MIDIOPEN             The MIDI output port is in use by
                             another process
  ERROR_NOMIDI               System does not have any MIDI
                             output devices installed

Remarks:
  Call this function before you use any other EasyMIDI functions.
  Failure to do so will cause the other functions to return zero
  until midiInitialize succeeds.

  If your application has an open console, program break messages
  are handled by EasyMidi to allow proper cleanup of the MIDI
  interface.  This special handling can be disabled by not having
  an open console before calling midiInitialize.  Calling
  midiUninitialize will remove EasyMidi's special break handling
  function from the console.

See Also:
  midiOutOpen


-----------------------------------------
midiNoteOn
-----------------------------------------

Sends a MIDI message to turn on a note on a given channel with
a given pressure.

BOOL midiNoteOn(int channel, int note, int pressure);

Parameters:
  int channel                The MIDI channel to send the message
                             on.  Valid values: 0..127
  int note                   The note number to play.  See the
                             remarks for more information on notes
  int pressure               The pressure to apply to the note.
                             Higher numbers result in louder
                             intensities.  Valid values: 0..127

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL       The channel parameter is invalid
  ERROR_BADMIDINOTE          The note parameter is invalid
  ERROR_BADMIDIPRESSURE      The pressure parameter is invalid
  ERROR_MIDISEND             Writing to the MIDI output port
                             failed

Remarks:
  When a note is turned on, it will remain on until it is turned
  off with either midiNoteOff or midiOutReset.  Channels allow
  songs to play notes of different instruments simultaneously.

  Valid note values range from zero to 127.  Middle C has a value
  of 60.  The length of an octave is 12, meaning that the value
  of C above Middle C is 72.  A note's sharp has the same value
  as the next note's flat.

See Also:
  midiNoteOff, midiWait, midiOutReset, midiOutShortMsg


-----------------------------------------
midiNoteOff
-----------------------------------------

Sends a MIDI message to turn off a note on a given channel at a
given velocity.

BOOL midiNoteOff(int channel, int note, int velocity);

Parameters:
  int channel                The MIDI channel to send the message
                             on.  Valid values: 0..127
  int note                   The note number to stop.  See the
                             remarks for more information on notes
  int velocity               How fast a note should stop.  Lower
                             values cause the note to fade longer,
                             and higher values make the stop more
                             abruptly.  Valid values: 0..127

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL       The channel parameter is invalid
  ERROR_BADMIDINOTE          The note parameter is invalid
  ERROR_BADMIDIVELOCITY      The velocity parameter is invalid
  ERROR_MIDISEND             Writing to the MIDI output port
                             failed

Remarks:
  Notes that are turned off with this function must have
  previously been turned on with midiNoteOn.  To create a delay
  between midiNoteOn and midiNoteOff calls, either use
  midiWait or some other delay code.

  If more than one note was turned on in the same channel, you
  still need to turn off each note if you want to make the channel
  silent.  That is, you must have a midiNoteOff call for every
  midiNoteOn call if you want to have a song that does not have
  any notes still on when it is done.  Even if the multiple notes
  in the same channel had the same note value (such as an
  orchestra effect), you still need to call midiNoteOff for every
  call to midiNoteOn.

  If midiHoldPedal is set on the same channel passed to this
  function, the note will not be turned off until midiHoldPedal
  is called with FALSE.  But if you unset midiHoldPedal without
  calling midiNoteOff, the note will continue to play until
  midiNoteOff is called on that note.

  Some instruments have longer play durations than others, and
  in some cases the note may already seem to be "off" when
  internally it is on.  Or, if a note is turned off before the
  entire note has been played, then the user will not hear the
  part of the note that normally comes after the point where
  the note was turned off.  Many notes repeat during longer
  play durations and will play for the entire time the note
  is on regardless of length, such as a violin.  A piano,
  however, does not repeat in most cases.

See Also:
  midiNoteOn, midiWait, midiOutReset, midiOutShortMsg


-----------------------------------------
midiInstrument
-----------------------------------------

Sets the instrument that new notes will use in the given channel.

BOOL midiInstrument(int channel, int instrument);

Parameters:
  int channel                The MIDI channel to send the message
                             on.  Valid values: 0..127
  int instrument             The instrument to use.  Read through
                             Appendix A for more information on
                             instruments.  Valid values: 0..128

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL       The channel parameter is invalid
  ERROR_BADMIDIINSTRUMENT    The instrument parameter is invalid
  ERROR_MIDISEND             Writing to the MIDI output port
                             failed

Remarks:
  This function allows you to set the instrument that the next
  note on the given channel, if any, will use.  Use midiNoteOn
  to turn on a note after calling midiInstrument to use the
  new instrument.

  See Appendix A for more information on using instruments and
  for the valid values.

See Also:
  midiNoteOn, midiNoteOff, midiOutShortMsg


-----------------------------------------
midiHoldPedal
-----------------------------------------

Postpones midiNoteOff messages on the given channel until
midiHoldPedal is called again.

BOOL midiHoldPedal(int channel, BOOL hold);

Parameters:
  int channel                The MIDI channel to send the message
                             on.  Valid values: 0..127
  int hold                   If TRUE, midiNoteOff messages are
                             postponed until midiHoldPedal is
                             called with FALSE in the hold
                             parameter.  If FALSE, any holds on
                             the given MIDI channel are released
                             and all waiting MIDI note off messages
                             are processed at the same time

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_BADMIDICHANNEL       The channel parameter is invalid
  ERROR_MIDISEND             Writing to the MIDI output port
                             failed

Remarks:
  This function delays MIDI note off messages in the MIDI
  processor until this function is called again to un-hold the
  messages.  The delay is implemented by the MIDI hardware and
  might not be supported by some MIDI devices.  This function's
  capabilities can be duplicated by moving all the midiNoteOff
  calls into one place where they are all called at once.

See Also:
  midiNoteOff, midiOutShortMsg


-----------------------------------------
midiWait
-----------------------------------------

Causes the current thread to do nothing for the given number of
milliseconds.  The Win16 version continually yields the processor
to other tasks until the given number of milliseconds has
elapsed.

BOOL midiWait(UINT ms);

Parameters:
  UINT ms                    An unsigned integer for the number
                             of milliseconds the delay should
                             last.

Return Values:
  Returns a non-zero value if the function was successful.  The
  Win16 version always returns non-zero.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized

Remarks:
  In the Win32 version, a zero value for ms will cause EasyMIDI
  to forfeit the remainder of its timeslice to other programs of
  the same priority.  In that case, the function will return
  almost immediately after a very brief delay, if any.  The Win16
  version always returns immediately when ms is zero.

See Also:
  Sleep (Win32 version); Yield, timeGetTime (Win16 version)


-----------------------------------------
midiGetHMidiOut
-----------------------------------------

Returns the HMIDIOUT handle that was opened when midiInitialize
was successfully called.  If midiInitialize failed or was not
called, then the returned value is not a valid HMIDIOUT handle.

HMIDIOUT midiGetHMidiOut();

Parameters:
  none

Return Values:
  The internal hMidiOut variable is always returned, regardless
  of its validity.

Remarks:
  Use this function if you want to call midiOutxxxx API functions
  manually.  When using the value returned from this function,
  avoid calling midiOutOpen and midiOutClose.  To close the
  handle, use EasyMIDI's midiUninitialize.

  Known functions that can be used with the value returned by
  this function include midiConnect, midiDisconnect,
  midiOutCacheDrumPatches, midiOutCachePatches, midiOutGetDevCaps,
  midiOutGetID, midiOutGetNumDevs, midiOutGetVolume,
  midiOutLongMsg, midiOutMessage, midiOutPrepareHeader,
  midiOutReset, midiOutSetVolume, midiOutShortMsg, and
  midiOutUnprepareHeader.

See Also:
  midiInitialize, midiUninitialize


-----------------------------------------
midiUninitialize
-----------------------------------------

Silences any playing notes and closes the MIDI output device.

BOOL midiUninitialize();

Parameters:
  none

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized

Remarks:
  This function calls midiOutReset before closing the MIDI output
  port.  Internal variables are freed at this time too, and the
  special handling for program break codes on the console, if
  installed, is removed.  Call this function when you are
  finished with EasyMIDI at the end of your program.

See Also:
  midiInitialize, midiOutReset, midiOutClose


=========================================
2.  Console Functions
=========================================

The console functions, only available in the Win32 version
of EasyMIDI, allow programs to use a standard Win32 console
to produce colorful output without requiring standard
libraries to implement textcolor and textbackground.
Besides, their implementations do not work in the libraries
that were tested so far.

These functions are safe for use in both single-threaded and
multithreaded applications.  If used in an application with
an active console, program breaks automatically clean up
the MIDI interface before closing the program.

Functions:

BOOL SetFgColor(int newcolor);
BOOL SetBgColor(int newcolor);
BOOL ClearScreen(void);
BOOL GotoXY(short x, short y);
DWORD WhereX(void);
DWORD WhereY(void);
BOOL Write(LPCTSTR lpszString);

Compatibility Functions:
#define gotoxy(x, y) GotoXY(x, y)
#define clrscr() ClearScreen()
#define textcolor(mode) SetFgColor(mode)
#define textbackground(mode) SetBgColor(mode)
#define wherex() WhereX()
#define wherey() WhereY()


-----------------------------------------
SetFgColor
-----------------------------------------

Sets the current foreground color on the console window that
was available when midiInitialize was called, if any.

BOOL SetFgColor(int newcolor);
#define textcolor(mode) SetFgColor(mode)

Parameters:
  int newcolor               A value for the new color.  Valid
                             values range from 0 to 15, and
                             can be one of the following:
                             BLACK, BLUE, GREEN, CYAN, RED,
                             MAGENTA, BROWN, LIGHTGRAY, DARKGRAY,
                             LIGHTBLUE, LIGHTGREEN, LIGHTCYAN,
                             LIGHTRED, LIGHTMAGENTA, YELLOW, and
                             WHITE

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                             midiInitialize was called
  Other values               Refer to the documentation for
                             the SetConsoleTextAttribute Win32
                             API function

Remarks:
  This function is only implemented in the Win16 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call textcolor(newcolor).

  In the Win32 version, BROWN's displayed color might look more
  like a dark yellow than anything while in window mode.
  Switching to full screen mode typically solves this problem.
  If using Win16, ScreenWindow properly initializes a color
  palette with a realistic brown.

See Also:
  textcolor, midiInitialize


-----------------------------------------
SetBgColor
-----------------------------------------

Sets the current background color on the console window that
was available when midiInitialize was called, if any.

BOOL SetBgColor(int newcolor);
#define textbackground(mode) SetBgColor(mode)

Parameters:
  int newcolor               A value for the new color.  Valid
                             values range from 0 to 15, and
                             can be one of the following:
                             BLACK, BLUE, GREEN, CYAN, RED,
                             MAGENTA, BROWN, LIGHTGRAY, DARKGRAY,
                             LIGHTBLUE, LIGHTGREEN, LIGHTCYAN,
                             LIGHTRED, LIGHTMAGENTA, YELLOW, and
                             WHITE

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                             midiInitialize was called
  Other values               Refer to the documentation for
                             the SetConsoleTextAttribute Win32
                             API function

Remarks:
  This function is only implemented in the Win16 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call textbackground(newcolor).

  Some video cards might not support background colors after
  LIGHTGRAY while in full screen text mode.  Switching to window
  mode should correct this problem.

  In the Win32 version, BROWN's displayed color might look more
  like a dark yellow than anything while in window mode.
  Switching to full screen mode typically solves this problem.
  If using Win16, ScreenWindow properly initializes a color
  palette with a realistic brown.

See Also:
  textbackground, midiInitialize


-----------------------------------------
ClearScreen
-----------------------------------------

Clears the screen and positions the cursor at the top-left corner
of the console.

BOOL ClearScreen(void);
#define clrscr() ClearScreen()

Parameters:
  none

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                             midiInitialize was called
  Other values               Refer to the documentation for
                             the SetConsoleOutputAttribute,
                             FillConsoleOutputCharacter, and
                             SetConsoleCursorPosition Win32
                             API functions

Remarks:
  The screen clears with the current background color.

  This function is only implemented in the Win16 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call clrscr().

  Some video cards might not support background colors after
  LIGHTGRAY while in full screen text mode.  Switching to window
  mode should correct this problem.

  In the Win32 version, BROWN's displayed color might look more
  like a dark yellow than anything while in window mode.
  Switching to full screen mode typically solves this problem.
  If using Win16, ScreenWindow properly initializes a color
  palette with a realistic brown.

See Also:
  clrscr, midiInitialize


-----------------------------------------
GotoXY
-----------------------------------------

Positions the cursor at the given (x,y) coordinates.

BOOL GotoXY(short x, short y);
#define gotoxy(x, y) GotoXY(x, y)

Parameters:
  short x                    The column to move to
  short y                    The row to move to

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                             midiInitialize was called
  Other values               Refer to the documentation for
                             the SetConsoleCursorPosition
                             Win32 API function

Remarks:
  This function is only implemented in the Win32 version of
  EasyMIDI.  Programmers using the 16-bit version should use
  the ScreenWindow library and call gotoxy(x, y).

See Also:
  gotoxy, midiInitialize


-----------------------------------------
WhereX
-----------------------------------------

Returns the current column of the cursor in the console window.

DWORD WhereX(void);
#define wherex() WhereX()

Parameters:
  none

Return Values:
  Returns a non-zero value equaling the current column in the console
  window if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                             midiInitialize was called
  Other values               Refer to the documentation for
                             the GetConsoleScreenBufferInfo
                             Win32 API function

Remarks:
  This function is only implemented in the second release of the
  Win32 version of EasyMIDI.  Programmers using the 16-bit version
  should use the ScreenWindow library and call wherex(x, y).

See Also:
  wherey, midiInitialize


-----------------------------------------
WhereY
-----------------------------------------

Returns the current row of the cursor in the console window.

DWORD WhereY(void);
#define wherey() WhereY()

Parameters:
  none

Return Values:
  Returns a non-zero value equaling the current row in the console
  window if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                             midiInitialize was called
  Other values               Refer to the documentation for
                             the GetConsoleScreenBufferInfo
                             Win32 API function

Remarks:
  This function is only implemented in the second release of the
  Win32 version of EasyMIDI.  Programmers using the 16-bit version
  should use the ScreenWindow library and call wherey(x, y).

See Also:
  wherex, midiInitialize


-----------------------------------------
Write
-----------------------------------------

Prints text onto the console at the current cursor
position.

BOOL Write(LPCTSTR lpszString);

Parameters:
  LPCTSTR lpszString         Long pointer to a constant
                             Unicode(tm) or ASCII string
                             to print on the console

Return Values:
  Returns a non-zero value if the function was successful.

  If the function failed, the function returns zero and sets the
  last error to one of the following (get with GetLastError()):

  ERROR_MIDINOTOPEN          EasyMIDI has not been initialized
  ERROR_NOCONSOLE            No console was available when
                             midiInitialize was called

Remarks:
  This function allows Unicode strings to print when using a
  Unicode-enabled version of Win32.  Windows NT and Windows CE
  both support Unicode internally on all Win32 API functions;
  Win95 and Win98 do not.

  On Win95 consoles, writing a newline may cause the remainder
  of the line, if any, to instantly take on the current
  foreground and background colors.  If this effect is not
  desired, then use GotoXY to manually move to the next line.
  This problem is not an issue with Windows NT unless if you
  are writing to the last row of the console.  Standard library
  implementations from both Microsoft and Borland also call
  WriteConsole and/or WriteFile, and this effect is duplicated.

  It is just as safe to call Write as it is to call standard
  library output and input functions.  If cout, printf, puts,
  etc. are used, the effects are the same (e.g., the text is
  written to the screen using the current colors and position).

See Also:
  GotoXY, cout, printf, puts, midiInitialize


=========================================
A.  General MIDI Instruments
=========================================

In MIDI, instruments are referenced by a 8-bit unsigned integer,
ranging from 0 to 128 (129-255 are invalid MIDI instruments).
The following instruments have been grouped for easy reference
by category (Pianos, Chromatic Percussion, Organs, Guitars,
Bass, Strings, Ensembles, Brass, Reeds, Pipes, Synth Lead,
Synth Pad, Background Tracks, Miscellaneous Strings,
Miscellaneous Percussion, Sound Effects, and Standard
Percussion).


-----------------------------------------
Pianos
-----------------------------------------

0   Acoustic grand piano
1   Bright acoustic piano
2   Electric grand piano
3   Honky-tonk piano
4   Rhodes piano
5   Chorused piano
6   Harpsichord
7   Clavinet


-----------------------------------------
Chromatic Percussion
-----------------------------------------

8   Celesta
9   Glockenspiel
10  Music box
11  Vibraphone
12  Marimba
13  Xylophone
14  Tubular bells
15  Dulcimer


-----------------------------------------
Organs
-----------------------------------------

16  Hammond organ
17  Percussive organ
18  Rock organ
19  Church organ
20  Reed organ
21  Accordion
22  Harmonica
23  Tango accordion


-----------------------------------------
Guitars
-----------------------------------------

24  Acoustic guitar (nylon)
25  Acoustic guitar (steel)
26  Electric guitar (jazz)
27  Electric guitar (clean)
28  Electric guitar (muted)
29  Overdriven guitar
30  Distortion guitar
31  Guitar harmonics


-----------------------------------------
Bass
-----------------------------------------

32  Acoustic bass
33  Electric bass (finger)
34  Electric bass (pick)
35  Fretless bass
36  Slap bass 1
37  Slap bass 2
38  Synth bass 1
39  Synth bass 2


-----------------------------------------
Strings
-----------------------------------------

40  Violin
41  Viola
42  Cello
43  Contrabass
44  Tremolo strings
45  Pizzicato strings
46  Orchestral harp
47  Timpani


-----------------------------------------
Ensembles
-----------------------------------------

48  String ensemble 1
49  String ensemble 2
50  Synth. strings 1
51  Synth. strings 2
52  Choir Aahs
53  Voice Oohs
54  Synth voice
55  Orchestra hit


-----------------------------------------
Brass
-----------------------------------------

56  Trumpet
57  Trombone
58  Tuba
59  Muted trumpet
60  French horn
61  Brass section
62  Synth. brass 1
63  Synth. brass 2


-----------------------------------------
Reeds
-----------------------------------------

64  Soprano sax
65  Alto sax
66  Tenor sax
67  Baritone sax
68  Oboe
69  English horn
70  Bassoon
71  Clarinet


-----------------------------------------
Pipes
-----------------------------------------
72  Piccolo 
73  Flute 
74  Recorder 
75  Pan flute 
76  Bottle blow 
77  Shakuhachi 
78  Whistle 
79  Ocarina


-----------------------------------------
Synth Lead
-----------------------------------------

80  Lead 1 (square)
81  Lead 2 (sawtooth)
82  Lead 3 (calliope lead)
83  Lead 4 (chiff lead)
84  Lead 5 (charang)
85  Lead 6 (voice)
86  Lead 7 (fifths)
87  Lead 8 (brass + lead)


-----------------------------------------
Synth Pad
-----------------------------------------

88  Pad 1 (new age)
89  Pad 2 (warm)
90  Pad 3 (polysynth)
91  Pad 4 (choir)
92  Pad 5 (bowed)
93  Pad 6 (metallic)
94  Pad 7 (halo)
95  Pad 8 (sweep)


-----------------------------------------
Background Tracks
-----------------------------------------

96  Ice Rain
97  Soundtrack
98  Crystal
99  Atmosphere
100 Brightness
101 Goblin
102 Echo Drops
103 Star Theme


-----------------------------------------
Miscellaneous Strings
-----------------------------------------

104 Sitar
105 Banjo
106 Shamisen
107 Koto
108 Kalimba
109 Bagpipe
110 Fiddle
111 Shenai


-----------------------------------------
Miscellaneous Percussion
-----------------------------------------

112 Tinker Bell
113 Agogo
114 Steel Drum
115 Wood Block
116 Taiko Drum
117 Melodic Tom
118 Synth Drum
119 Reverse Cymbal


-----------------------------------------
Sound Effects
-----------------------------------------

120 Guitar fret noise
121 Breath noise
122 Seashore
123 Bird tweet
124 Telephone ring
125 Helicopter
126 Applause
127 Gunshot


-----------------------------------------
Standard Percussion (Instrument 128)
-----------------------------------------

The values listed are the note numbers to
use for the given sound on instrument 128:

35 Acoustic Bass Drum
36 Bass Drum 1
37 Side Stick
38 Acoustic Snare
39 Hand Clap
40 Electric Snare
41 Low Floor Tom
42 Closed High-Hat
43 High Floor Ton
44 Pedal High-Hat
45 Low Tom
46 Open High-Hat
47 Low-Mid Tom
48 High-Mid Tom
49 Crash Cymbal 1
50 High Tom
51 Ride Cymbal 1
52 Chinese Cymbal
53 Ride Bell
54 Tambourine
55 Splash Cymbal
56 Cowbell
57 Crash Cymbal 2
58 Vibraslap
59 Ride Cymbal 2
60 High Bongo
61 Low Bongo
62 Mute High Conga
63 Open High Conga
64 Low Conga
65 High Timbale
66 Low Timbale
67 High Agogo
68 Low Agogo
69 Cabasa
70 Maracas
71 Short Whistle
72 Long Whistle
73 Short Guiro
74 Long Guiro
75 Claves
76 High Wood Block
77 Low Wood Block
78 Mute Cuica
79 Open Cuica
80 Mute Triangle
81 Open Triangle


=========================================



Written by Steven Lawrance on 8-20-1998
Revised on 12-2-1998 by Steven Lawrance for Release 2


Portions copied from the Microsoft Platform SDK reference
on MIDI instruments, and from Creative Labs's AWE Control
Panel v2.07.0.  This document is for educational use only.

All trademarks belong to their respective owners.