Piano, fretboard & Hammered dulcimer simulator/composer

Table of Contents:

 Installation
 Introduction
 Getting started
 Editing .HDS song files
 Midi channels
 Fretboard map
 Hammered dulcimer map
 General performance tips
 Checking timing and tempo performance
 How to convert an .HDS file to a .mid file
 Midi instrument choice
 Contact and program history


Installation:

This is a Visual Basic program.  Visual Basic programs require that certain files be present in the user's Windows\System directory for them to run properly.  These are called 'Run Time' files.  In most cases, these files are already present on the user's system, and so no further action is necessary.  In a very few cases, however, some users may find that they cannot run this program on their system, and may receive one of various error messages if they try to do so.  This is caused by the fact that either these files are *not* present on their system, or, the files are there, but the version #'s are old.  This can be solved by downloading and installing the latest 'Run Time' files from Microsoft (currently at Service Pack 5), at: http://www.microsoft.com/downloads/release.asp?releaseid=28337.  It's not a large download.


Introduction:

This program does several things:

  1. It lets you open the Midi ports for Input, Output, or Thru
  2. You can play notes from an externally connected instrument, or the piano keyboard pictured on the screen.
  3. You can also play songs that have been written for HDMapper.
  4. You can record the songs to .mid files.
  5. You can send immediate commands to the midi output device.

This program was inspired by HDMapper (link above), written by Pete Royston & Carl Hungerford

This program includes example code found at http://www.codeguru.com/vb/gen/vb_multimedia/article.php/c1095/

Differences between this program and HDMapper:

  1. You can change the midi sounds to any of 128 different instruments, and vary the note on and note off velocities.
  2. You can close the Midi port(s) when necessary, so you can release them to another application, without having to close the program.
  3. It has the ability to also allow external instruments from the Midi input port.
  4. It displays the piano keyboad, fretboard and musical scale as well as a hammered dulcimer image.
  5. You can mark and play a specific selection of notes in the notes listbox using your mouse.  To clear the selection, click a note, then press Ctrl and click it again.
  6. You can deselect the 'Highlight each note as it plays' checkbox so that the song will play at the correct tempo.
  7. In this program, you edit an .hds song file using an external text word processer (Notepad is fine), or Excel or another spreadsheet program.  Starting w/version 6.0, a function was added which makes it really easy to edit PolyDur syntax files.  See below for details.
  8. In the listbox, notes are shown a little differently.  'D4-3', for instance, means it's the D note in the fourth octave, played on hammered dulcimer bridge #3.
  9. Starting w/version 5.0, the 'PolyDur' enhancement was added to .HDS files (see below).
  10. You can have a double dotted note as well as single dotted, like 4..

Most selections that you make, are saved to a file named Application.ini so that they are restored when you next run the program.


Getting started:

When you run the program, you first have to click the 'Sound' menu, then 'Select ports', and open the midi port(s).  Most users will want to pick the 'Midi Out w/mouse...' option.  The other options are for advanced users.  Anytime that you want the program to release the ports to another application, pick the 'All ports close' option.

When you play notes, if you don't hear anything, double click the small speaker icon in your system tray, which opens up Volume control, and make sure that the Midi isn't muted.


Editing .HDS song files:

These use the same syntax as HDMapper:

At the top of the .hds file, is the [Song] header section, which looks like this:
[Song]
Name=Oh Susanna
Beats Per Measure=4 (incorrectly listed as 'Beats per Min' in HDMapper's docs).
Single Beat Note=4
Pace=120 (this specifies the tempo, that is, how many of the 'Single Beat Notes' would be played per minute).

After the [Song] section, is the [Notes] section.  In the [Notes] section, the syntax is [Duration] [Note] [# or b] [+ or -] [Bridge #]:

  1. Duration can be 4 for quarter note, 1 for whole note, 8 for 8th note, etc. You can also specify one or 2 dots, for instance, 4. would mean to play the note for 1.5 times as long as a quarter note, 4.. would mean to play it for 1.75 times as long.
  2. Note is C, D, E, etc.
  3. # = sharp, b = flat
  4. optional '+' signs specify how many octaves above the middle C (4th) octave.
  5. optional '-' signs specify how many octaves below the middle C octave.
  6. Bridge # is optional, specifies which hammered dulcimer bridge to play the note on.
  7. Blank lines and lines beginning with a semicolon are ignored.
  8. If other notes are to be played at the same time, separate them with slashes (/).

Starting with MidiMapper version 5.0, the PolyDur extension was added.  This gives the ability to make more flexible .hds song files.  Here are what you can add:

  1. To use these new features, add the 'PolyDur=True' line before the [Notes] section.  Also, add a 'PolyPhony=X' line after it, where 'X' specifies the maximum # of fingers or channels to use (without that line, the default is 3 note polyphony).
  2. PolyDur means that the notes in each interval and chord can have different durations, for instance, in the line '16C+2/8A+2/4R', the first finger or hammer plays a 1/16 note, the 2nd, an 1/8th note, and the 3rd is a quarter rest (R means rest).
  3. On each line, separate the notes with '/' to separate the line into the # of note polyphony you want.  If no note is to be played by a finger or hammer on that line, insert just 'x' for that finger or hammer.  This is necessary so that each finger has the correct number of beats per measure, otherwise they'll become out of sync when you play the song.
  4. You can copy, move, and delete channels (voices) by opening or importing the .hds file into Excel or another spreadsheet program:
  5. 'T' before a note specifies to play this note as a triplet.
  6. 'Sb' before a note specifies to start a slur or tie for this finger or hammer.
  7. 'Se' before a note specifies the end of a slur/tie.
  8. 'Lb' before a note specifies to start a legato sequence for this finger or hammer.
  9. 'Le' before a note specifies the end of a legato sequence.
  10. '[Repeat XXx]' means to repeat this section X times until [Repeat End) is encountered (maximum 10 repeats).
  11. '[Ending XX]' means that this is an alternate ending in the Repeat section.  You can only have either *no* alternate endings, or the same # of endings as the # of repeats for this section.
  12. All the [Ending XX] sections must be contained inside the Repeat section, except the last, which may immediately follow the [Repeat End] line.  In this case, you're saying that the rest of the song that follows is the last ending for that Repeat section.
  13. Any Repeat section, even nested ones, can have alternate endings.

    Here is the order that must be followed for repeat sections:
    [Repeat Xx]
    ...
    [Ending 1]
    ...
    [Repeat End]
    [Ending 2]   (The last alternate ending can be either before or after the [Repeat End] line)
    ...etc.

  14. You can change the tempo of the song by using a line like '[Tempo= 1/4 = 85]' under the [Notes] section.  In this case, it's saying that the tempo is equivalent to 85 quarter notes played per minute.  In the header section, you specify the *beginning* tempo in the 'Pace=' field, and there, it's understood that the tempo is equivalent to that many 'Single Beat Note=' notes played per minute.
  15. The last number of each note designates the bridge to play the note on, same as HDMapper.  I'm not a hammered dulcimer player, so I may have designated the wrong bridge in the included samples.  If you'd like to correct them, I'd be happy to include your corrected .hds files in the next version.
  16. You can enter instrument volume dynamic changes like '[Inst. 2 dyn. = mf]'.  What that says is to change instrument or voice 2 to mf.  Allowed values are pp, p, mp, mf, f, and ff.  See 'How the Note ON velocities and Dynamics work together' in the next section for more about this.

    For an example of how these are entered, see the included song 'Bridge Over Troubled Water.hds'.

  17. You can enter raw midi commands in the form '[Midi Msg Data1 Data2]'.  For example '[Midi 192 11 0]' would change channel 1 instrument to Vibraphone (the values are 0 based, rather than 1 based).  Be aware that some messages only work when sent to a real instrument connected to the output port, and some messages aren't supported by all soundcards.  You can change instruments, pan, volume, and add reverb and other special effects using this command.  If you enter hex values, prefix them with '&h'.  The program requires 3 values, so if the 3rd value isn't used for a command, use 0.  You can find sites on the internet that list all the possible messages.  Here's one: http://www.borg.com/~jglatt/tech/midispec.htm.  In most cases, make sure, if you send a controller message, to also send another message at the end of the song to reset it, otherwise the first controller setting might persist when you play a different song.  You can also send immediate midi commands from options under the 'Sound' menu.

    How to make a song repeat and fade at the end of the song: See Both Sides Now.hds and Windy.hds for examples of how to do this.

  18. Key sig changes, entered like '[Key sig=G]', Time sig changes, entered like '[Time 4/4]', and score marker notes, entered like '[Score marker A]', are ignored while playing but are written when you save the song as a .mid file. (see below).
  19. [Bar XX] and other lines that start with '[' are ignored, but you can use them for comments.

The PolyDur enhancement makes it possible to enter most, if not all, western music exactly as it appears in the original score.  Bridge over Troubled Water, Desperado, and most of the other included samples were entered exactly from the original composer's scores.

Starting w/version 6.0, a new function was added which makes it really easy to edit PolyDur syntax files.  Click the 'Edit Polydur song' under the 'Edit' menu to access this.  Using this function, I created Joni Mitchell's song 'Both Sides Now' in about an hour, and included it in the package as 'Both Sides Now.hds'.  This screen allows editing of songs with 2 to 12 note polyphony.


Midi channels:

Polydur format songs can use up to 16 voices, each sent to a separate midi channel; a different instrument can be assigned to each.  To set the instrument, velocity on and off for each channel, click the channel settings frame with the left or right mouse button.  The default is that if you left-click, the channel # will decrease, right will increase, but you can swap this behavior by changing the 'ChannelClickIncrease' setting in Application.ini.  Close the program first before editing Application.ini, then start the program again to use the new setting.

To change the instrument #, velocity on and off, type in the number and press enter, or use the up-down arrows, or click the frame to change to a different channel.

How the Note ON velocities and Dynamics work together:

When clicking the piano keyboard with the mouse or playing an .hds song, the Note ON velocity is multiplied by the current, or default Dynamic before playing each note (Dynamics can also be coded to change while a song is playing, see how to do this in the previous section).  You can change the default Dynamic from the 'Sound' menu.  When you select that, you'll see something like this:

The image shows that my default dynamic is Mezzo-forte.  The multipliers on the right are defined in Application.ini.  These are configurable by first closing the program, then opening Application.ini in Notepad and changing them:

The default settings are Note ON velocity of 90 for all channels, and Mezzo-forte as the default dynamic, in keeping with the convention that, if no Dynamic is specified in sheet music, that Mezzo-forte should be used.  Here are the default multipliers in Application.ini:

DynFactorPP=0.53
DynFactorP=.7
DynFactorMP=.85
DynFactorMF=1
DynFactorF=1.13
DynFactorFF=1.28

If you have small speakers, those might create too harsh a sound.  If so, you can reduce them, or set them all equal to 1 (which would apply no factor at all), or reduce the Note ON velocity settings.  After changing and saving Application.ini, restart the program to use the new values.

Some feel that this method of changing the dynamic by varying the Note ON velocity, works best for percussive instruments, such as piano and guitar, but that entering channel volume or expression changes instead, using raw midi commands (see #17 above), works better for wind or other instruments.  Experiment to see what you like best.

Resetting the soundcard or midi module:

If the stereo balance, volume, or other music qualities don't sound right, try 'Reset midi controllers' from the 'Sound' menu to reset them to defaults.  If instruments don't sound correct, try 'Send GM reset' which resets the instrument #'s to the General Midi specifications.  The instruments might have changed if you played a .mid file in another program, then came back and tried to play a song in MidiMapper.

Flanging:

Flanging occurs when 2 or more voices (channels), playing the same instrument, play the same note and same octave simultaneously.  You should avoid this generally, because it sometimes results in a muted sound, caused by the harmonics of the notes overriding or cancelling each other.

How to mute or reroute one or more Midi channels:

Let's say that you want to mute the high voice because you want to play that part on your violin instead, as the song plays.  There is a function in Windows that allows you to route each of the 16 channels to either your soundcard, an external instrument, or to 'None'.  This function is called 'Midi Mapper', which is the same name as this program but that's just a coincidence.  To access this function, click 'Start', 'Settings', 'Control panel', 'Multimedia'.  Then, click the 'Midi' tab, then select 'Custom configuration', then 'Configure'.  Once you have made your changes, then, in this program, MidiMapper, click the 'Sound' menu, then 'Select midi ports', then change the output to Windows' 'Midi Mapper' driver to hear the results.

If you just want to mute one channel temporarily, it might be easier just to enter a channel volume of 0 in the .hds file for that channel.  To do that for channel 1, would be '[Midi &hB0 7 0]'.

Channel priorities and problems with 'dropped notes':

This is usually only a problem for older sound cards.  From Creative Labs:

"MIDI devices use a system of Channel Priorities 1 through to 16 with the Percussion Channel 10 getting the highest.  The channels with the higher priority may cause the channels with lower priority to drop notes if the polyphony that is supported by the midi module is exceeded.  Therefore, it is recommended to allocate the solo instruments to the lower channels and strings and piano to the higher channels."

If you have a problem with clipped/dropped notes, you might be able to solve it by adjusting the Note OFF/ON delay, which is an option under the 'Sound' menu.  See more about this here.


Fretboard:

Version 3.0 adds a guitar fretboard.  You can also make other fretboards, for instance, for banjo, mandolin, and mountain dulcimer, or similar non-fretted instruments like violins.  I've only created the guitar fretboard because I don't play those others.  I'd like to add those others to the package, so, if you make one, please send it to me, and I'll put it in the package along with credit information.  It's easier than it looks, by the way:

To make a new fretboard map:

  1. Create an image.  You can use GuitarFretboard.gif as an example.  The new image width and height shouldn't be any larger than that image, but either dimension may be smaller.  Use as few colors as possible, preferably just black and white.
  2. Make a *.frt fretboard definition file.  You can use Guitar.frt as an example.  Open that file up in Notepad to see more instructions.
  3. To define the position of notes on the strings is really easy.  Once you have the image created, and a minimal .frt file that includes at least the FretBoard= and LeftFinger= defined, you can open it up in the Midi player.  Then, you can find where you want to place notes by just right clicking on the image, and copying the cursor coordinates to the clipboard.  From there, you can then paste them into your .frt definition file.  The Key= syntax is the same as HDMapper, mentioned above.

Shortcuts:

Once you've defined the first Top= position for a string, you can of course copy that to all the other notes for that string and just change the Left= and Key= for each.

Once you've defined the notes for one string, you can probably copy the whole block to the next string and just change the Top= and Key= for each note, etc.

It only took me about 45 minutes to make the Guitar fretboard map.

See the HDMapper documentation for more about making .dlc files, because .frt files use the same syntax.


Hammered dulcimer map:

If you maximize the window to at least 1024x768, you can load a hammered dulcimer image map, similar to HDMapper.  The fretboard map will disappear to make room.  Making a hammered dulcimer map is similar to the docs in HDMapper and the fretboard instructions above.  Additionally, just as for the fretboard, you can right click on the image to get cursor coordinates to make it easier to add notes to the .dlc file.  The hammered dulcimer image shouldn't exceed 518 pixels in width and 367 pixels in height.

Program Issue: This program doesn't correctly determine, for a given note, whether the left or right hammer should be used.  If you want to see the correct hammer choices when playing .hds files, use HDMapper.  The main benefit of loading the hammered dulcimer in *this* program, is that you can more easily make a new .dlc file using the right-click function mentioned above.  If you have an idea about how I can add an algorithm so that my program can make the correct hammer choices for notes, let me know.


General performance tips:

For slow computers especially, the most precise note timing can be accomplished by unchecking the 'Highlight each note as it plays' and 'Show animation' checkboxes.  Also, just like any other media player, you may notice a pause if another program in the background causes a 'system' event, like checking mail, instant messages, and calendar programs.  So, it's best to keep those to a minimum.


Checking timing and tempo performance:

If you select 'Calculate lag statistics' under the 'Performance' menu, then, after each time you play a Polydur .HDS song, a small window will appear that will tell you 'Actual song time', 'Predicted time' and some lag statistics.  The first figure will probably always be a few seconds longer than the second, because it also includes the extra time caused by sending several extra messages to the midi device, which I was unable to estimate and add to the 2nd figure.  The other statistics measure the approximate time, in milliseconds, from when one note for a finger/hammer starts to end til just after the next has started to play.

If you want to reduce lag, you should close other programs that are running; however, you may instead want to increase lag.  To do this, and understand why you might want to increase it, click the 'Note OFF/ON delay' option under the 'Sound' menu.  Lately, I've been setting the Note OFF delay to 0 when playing .hds songs in MidiMapper (which already induces a small amount of lag anyway), but setting it to 1 when recording to a .mid file in silent mode (which otherwise induces no lag).  You also might find that you can create a 'gospel' feel to a song by adding some lag.  Experiment with this to see what you like.

The longest lag that was detected and the line in the listbox that caused it, and the average for all notes, is displayed.

Consider that, if the song tempo is 120 quarter notes per minute, then each whole note takes 2 seconds, each 1/32 note around 62 milliseconds, and each 1/64th note around 31, etc.  So, lags below that are probably undetectable.

After you're satisfied with the timing, you might want to de-select this option because using it also adds a small amount of lag.


How to convert an .HDS file to a .mid file:

There is a new 'Save as .mid file' option under the 'File' menu to do this.  Previously, you had to install a midi loopback device driver and use an external sequencer, but not any longer.  Just click the option and follow the prompts.  If you'd like to edit the newly made .mid file further, including adding more tracks, changing tempo, or adding notes or information, I've also written a midi sequencer/recorder available here: members.fortunecity.com/whb11/Midi/MyMidiSequencer.htm  Important: Version 1.6 of my sequencer has some important fixes, so if you have an earlier version, you should upgrade.  On that page also is a really nice audio player to test your new .mid files, and play any other audio files also.

Key sig changes in the .hds song, entered like '[Key sig=G]', Time sig changes, entered like '[Time 4/4]', and score marker notes, entered like '[Score marker A]', are saved to Track 1 of the .mid file.

For the most accurate note timing, also follow the recommendations starting under 'Performance tips' above before recording.

Note: I acquired the internal .mid recording module from another company and it has a couple anomalies:

  1. When you save each new .mid file, you can't overwrite an existing file, you have to give it a new name each time, and
  2. While this program is open, you can't move, rename or do anything else to the new .mid files in Explorer, until you exit the program.

What's happening in both cases is that the module is locking the files and not releasing them until you exit, but, as I don't have the source code for the module, I can't change that.  But, it's a minor inconvenience.

If you need further help, ask me.


Midi instrument choice:

You can select your choice of instruments, however, the instrument selection and sound quality is up to your soundcard.  These are the General Midi specifications which nearly all devices use, but consult your device's user manual to make sure:
PIANOCHROMATIC PERCUSSION
1  Acoustic Grand9  Celesta
2  Bright Acoustic10  Glockenspiel
3  Electric Grand11  Music Box
4  Honky-Tonk12  Vibraphone
5  Electric Piano 113  Marimba
6  Electric Piano 214  Xylophone
7  Harpsichord15  Tubular Bells
8  Clavinet16  Dulcimer

ORGANGUITAR
17  Drawbar Organ25  Nylon String Guitar
18  Percussive Organ26  Steel String Guitar
19  Rock Organ27  Electric Jazz Guitar
20  Church Organ28  Electric Clean Guitar
21  Reed Organ29  Electric Muted Guitar
22  Accordian30  Overdriven Guitar
23  Harmonica31  Distortion Guitar
24  Tango Accordian32  Guitar Harmonics

BASSSOLO STRINGS
33  Acoustic Bass41  Violin
34  Electric Bass(finger)42  Viola
35  Electric Bass(pick)43  Cello
36  Fretless Bass44  Contrabass
37  Slap Bass 145  Tremolo Strings
38  Slap Bass 246  Pizzicato Strings
39  Synth Bass 147  Orchestral Strings
40  Synth Bass 248  Timpani

ENSEMBLEBRASS
49  String Ensemble 157  Trumpet
50  String Ensemble 258  Trombone
51  SynthStrings 159  Tuba
52  SynthStrings 260  Muted Trumpet
53  Choir Aahs61  French Horn
54  Voice Oohs62  Brass Section
55  Synth Voice63  SynthBrass 1
56  Orchestra Hit64  SynthBrass 2

REEDPIPE
65  Soprano Sax73  Piccolo
66  Alto Sax74  Flute
67  Tenor Sax75  Recorder
68  Baritone Sax76  Pan Flute
69  Oboe77  Blown Bottle
70  English Horn78  Skakuhachi
71  Bassoon79  Whistle
72  Clarinet80  Ocarina

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

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

PERCUSSIVESOUND EFFECTS
113  Tinkle Bell121  Guitar Fret Noise
114  Agogo122  Breath Noise
115  Steel Drums123  Seashore
116  Woodblock124  Bird Tweet
117  Taiko Drum125  Telephone Ring
118  Melodic Tom126  Helicopter
119  Synth Drum127  Applause
120  Reverse Cymbal128  Gunshot


Contact and program history:

Send feedback to: baldwinwh (at) netscape (dot) net

thanks
Web site: http://members.fortunecity.com/whb11/Midi/MyMidiPlayer.htm
You should check the website periodically for new versions and also new .hds songs.
Credit: Inspiration, and the .dlc, .hds, and .bmp files from HDMapper.

(Click for full version history)