By David Woolls - author of the VSMM tools.

VSMM stands for Very Structured Melody Maker, and is a development of the Wbargen tools (Bargen stands for Bar Generator).  All are primarily designed as composition aids but, rather than the simple constructions of the lower numbered Wbargen's, VSMM produces complete compositions in four part harmony and with cadential harmonic progression, which is rather more than the author originally intended.  This note concentrates on VSMM, but Tim has left all the earlier tools in the Tools2 menu, partly because they all produce something a little different and partly to provide a history of the development for those of you interested in the process. 

1. First make sure you have the latest release of Keykit. These notes refer to VSMM 3.1, although the central operation is the same for VSMM 3.0.
2. Bring up the VSMM tool, with Tools2->VSMM 3.1
3. What you see is a large number of buttons at the top and a blank space at the bottom.  The lower half is in fact a fully functioning, although slightly modified, Group Tool which is automatically filled and can be modified by the top section.
4. To see what it does just hit the Make button.  This gives you a drop down menu.  Choose New Variation and the lower half of the screen will fill with the Merged track and Tracks 1 to 4. 
5. Click the Play button and you will hear a composition lasting 40 bars, in the key of C and in 4/4 time. (You can use the normal right mouse click to start as well, but the play button will always Play when the mouse button has been set to a different instruction in the lower section).
6.  It will probably not be the most wonderful music you have ever heard but it will be fully harmonised, have a structure which moves in 4 bars, each section will finish with a cadence of some sort and the final bar will finish with a perfect cadence.  The final four bars will normally be the same as the first four.
7. If there are interesting phrases but you don't like the full composition you can choose Make->Current Variation, and the program will use the existing generated material and write you a new composition.  If you don't like it at all choose Make->New Variation.  You don't need to stop the playback, the program does that for you.
8. Compositions are not repeatable, so if you like what you hear save it before re-making.  Click File->Save, and enter a file name. In the version which should be in the latest download by the time you read this, you don't need to enter the .mid suffix and the program will save both the midi file and a copy of the page ( a .kp file).  For earlier releases, as with Keykit normally, add the .mid suffix. 
9. You will see a message in the console window like D:/Keykit72h/Music/KKNotes3.mid has been written. D:/Keykit72h/Music/KKNotes3.kp has been written. You will also see the full pathname in the Name: section at the top of the music section, beside the Merged button.
10. Tip: Because you can compose in any key, major or minor and in a variety of time signatures, it is a good idea to incorporate both in your titles, so that if you are looking for a 2/4 march in D, or the piece you wrote in G minor and 7/4, you can locate it by this information in the name.
11. You can recover the majority of the settings when you choose File->Read and pick a midifile created by VSMM.  The tool won't allow you to load a track with more than 4 tracks, which most other programs generate.  (To recover everything recoverable, use Page->Read and choose the .kp file with the name of the midifile you saved as a new VSMM tool).
12. You may have noticed the absence of the trademark 'black splodge' in the Merged track.  This is because VSMM picks up all the data held in that splodge, which are primarily the tempo, key and time signature, and places them in the appropriate places in the upper section.  It is also helpful to have a clear view of the full chords when doing editing in the lower section.
13. You can use the Bar range selectors O> and <32 (or howver many bars there are) to do pick or expand a section.  If you have 32 bars and want to see the last four, set the first range, which will have 1 in it to 29, then hit View.  If you want to hear bars 17 to 20, set the left range to 17, the right to 20, click on Pick.  Those bars will then change to red. Now click on Play, and the playback will start at 17 and stop at the end of 20.  You can use the normal Pick and View options which go with the embedded group tool if you can see which bits you want.  These buttons just let you ask for precisely the section you want, without having to guess the start and end point. 
14. Tip: All the buttons on the right side refer to the current Pick, so you can Re-harmonise, Transpose or Melodise individual bars or sections, if you want to hear what it sounds like. 
15. Tip: Pulling the Undo button off the Edit section is a very good idea.  You will use it a lot when experimenting.  To do this click Edit->Undo and holding the mouse down pull to the right.  Then put the resultant Undo button somewhere useful.

What is happening

16. When you choose Make the program generates a random number which it uses as its starting point.  This will always be different and even if it wasn't the composition would always sound different because it uses several random number generators to make its decisions, which is why you should save anything you think you might like to do something with later. 
17. VSMM is set by default to generate 8 different 4 bar lines.  You change the number of lines by clicking T8 and choosing one of the other options.  Giving the program less lines to choose from increases the probability of the same lines appearing in different voices.  You change the number of bars by clicking on the number beside Bars and choosing a different set.  Four bar sections are common in classical and contemporary music, but the program will make what you like best.
18. As you will have guessed by now, clicking on the 4/4, allows you to change time signature.  The current time signature appears on the button once you have done this.  The same goes for the key you want to compose in, where you click on C, in the first instance, and clicking on Major gives you other options.  The 5 to 8 melody lines are composed taking account of the time signature, giving appropriate groupings of notes for the underlying rhythm implied by the time signature. At least 2 of the lines will have longer note lengths than the rest, which produces the different pace in a couple of  the four channels which you can often hear.
19. Using the current settings, VSMM then chooses between one and four of the generated lines for each of the number of Sections, which default to 10, but can be changed in the same way as Bars by clicking the number beside Sections.  VSMM can choose the same set of four melody lines or different ones each time, or combinations of the two.  Or it can simply repeat either the previous section or the first section in their entirety.
20. By default the harmonising setting is H4, and you know how to change that by now, although it does give the most satisfying musical output, so you will probably want to leave it set.  H4 moves along a built-in harmonic progression using the circle of fifths.  It harmonises each section as it is built.  It can jump segments of the sequence but will always provide a cadence at the end of a section.  Chordal harmony is decided by the position in the sequence and by the selection of either root or an inversion for the placing of the notes vertically across the voices. 
21. The chords themselves are formed by the vertical alignment of the note values of the various strands from the selected generated sections.  You can get false harmonies and doubtful suspensions where the note values do not coincide in length, or can get sections with block chords marching along where they do, sometimes too many of them.  You can always edit out the bits you don't like, but most of the time the music will sound reasonably good, although not infrequently as if it has been harmonised by a novice music student with a hangover.
22. The notes in between the chords, where shorter note values in one line have no matches in the other lines at that time position, are moved by the Melodiser function, built into H4 but available as a button too. This makes sure that the passing notes are in the right scale and also stops the music from leaping about in single lines too much.  It also sometimes means that the starts of repeated sections are not identical to the original, since they are lined up with the closing chord of the previous section.

Subsequent Exploration

• To hear what untreated output sounds like, or if you just like an interesting noise as opposed to harmony, set the H4 button to As it comes.  You can hear how much work the program has to do to get to H4 output.  H1 to H3 are earlier attempts at providing chordal harmony.  You don't get progression with these, but the chords sound correct.  
• The time signatures really do make a difference to the sound of the output.  A few extreme ones are included which can give very interesting syncopation effects, but even the regular ones are worth exploring. 
• There is a Make->Autogen option, which chooses different time signatures for different segments.  This can produce some eccentric effects, if you are so minded.
• VSMM automatically puts the latest construction into the Snarf, so you can open a Group Tool, File->Read->Snarf and then File->Misc->Split on channels, to get the four tracks showing.  Or you can use the Window-Copy method from Keykit Notes 1.
• Remember that the tracks in the lower section have all the facilities of the group tool, so you can change instruments, mute tracks, or Snarf individual tracks or sections. Although it writes whole compositions, it is not likely to produce entirely satisfying tunes much of the time, so just take the bits you think you can do something with and stitch them together in a Group tool.
• Those of you who like a lot of repetition can try re-setting the 5ths button to 3rds or 2nds.  These use different harmonic progressions and the rules are not quite right, so a lot of chords are repeated.  Good for practice in improving the harmonies!  The adventurous musician/programmers might want to delve into the code and improve it.  The method in vsmm31.k is smmsetchord() .

Caveats

• When you use Re-Harmonise H4 you won't get the nice cadential endings, so you need to do them yourself if you want them.