Dirk Bertels

The greatest malfunction of spirit
is to believe things (Louis Pasteur)

Create your own Sessions in Piano Groove Tutor v0.7


Before downloading ...
Looping issues
Midi issues
Creating your own sessions: Overview
Create MIDI files
Edit MIDI files
Create the score
Edit the score
Archive the files


Last updated on 27 January 2011

The Piano Groove Tutor went through 2 more implementation stages since its introduction with v0.5:

  1. Addition of lock buttons so that both tempo and volume can be locked for all the grooves. This eliminates having to reset them each time you change grooves or sessions.
  2. Quite a few changes in implemention to facilitate people adding their own grooves. While previously the metronome tracks had to be hardcoded in the midi file, v0.7 automatically creates metronome tracks on the fly. I also made changes so that the SW detects the instruments by channel number, rather than patch number.

The changes also made it possible to simply add your own midi files without scores, they will still need to be organised in session folders as well as archived into a jar format (more on that later). The only requirements on the midi files is that the right hand is on channel 1, left hand on channel 2, bass on channel 3 and drums on channel 10. It is not a requirement that all of these channels are present.

There are a lot of user comments on the previous version that are still relevant to this version. If you have problems it may pay to look through those comments first at the version 0.5 comments page.

back to index

Before downloading ...

Before downloading the Piano Groove Tutor, you need to take care of 2 things:

  1. Have a recent version Java JRE installed (version 1.6 onwards)
  2. Ensure that this JRE contains a soundbank. To check whether your Java JRE contains a soundbank, go to the JRE folder (typically located at C:\Program Files\Java\<jre version> on a Windows machine) and navigate to the \lib folder. See if an \audio folder is present and whether it contains a sounbank file (.gm extension). If not, you can manually add this file yourself by downloading it from the Java Soundbank Download page.

To make it easy on yourself, you can take care of both at the same time by downloading the off-line version of JRE6. As of 20 Feb 2011, the link for a Windows PC was Java Downloads Page and navigate to the latest JRE6 yourself. Just remember that the on-line version does not contain the soundbank while the off-line one does.

Another way to update your JRE on windows is to go to Control Panel → Java → update. But this doesn't guarantee you get the soundbank...

You can verify your java version at Oracle's verify JRE website.

There is a Comments section at the end of this page. If you have some spare time, please use it.

back to index


Download version 0.7 of the piano Groove Tutor here: Piano Groove Tutor - version 0.7.2.

Note that it doesn't contain any grooves yet. You need to download these seperately from the Piano Groove Tutor Sessions page.

Place the session jar files into the application's Sessions folder, and they will become visible to the application on next startup.

Unzip it to a suitable location. The resulting folder should contain a java jar executable, an 'images' folder, and a 'sessions' folder (plus a couple of application files). To start the application, double click on the executable jar (in most Window systems). For convenience sake, in Windows, unzip it to something like Program Files\Piano Groove Tutor\ and add a link to it on your desktop.

If you have trouble, check the version 0.5 commentspage or leave a comment at the end of this page.

back to index

Looping issues

The Java looping system has some limitations:
  • Settings are from the beginning of the first field to the end of the second field; i.e. looping 1.1 to 1.4 plays the whole first bar (assuming 4/4 time signature). This may be counter-intuitive at first. It is done to avoid having something like 4.1 to 1.1 to indicate a range over the 4th bar.
  • You can't loop from a late part of a groove to an early part of the same groove, i.e. loop setting 1 has to come before loop setting 2.
  • The MIDI is not quantized, meaning some keys on the keyboard may not show, or show inadvertendly, at the beginning and end of a loop section. It would be easy to apply quantization, but it would be at the cost of musicality.
  • You can't change the loop setting while playing. This is fixable by adding a listener - may be something for next version.

back to index

Midi issues

Your computer may not have its MIDI working properly. When the Piano Groove Tutor starts up, the info window will show your MIDI configuration. At the end of the list you should see something like

		FOUND SEQUENCER: Device 6: Real Time Sequencer - false
		FOUND SYNTH: Device 7: Java Sound Synthesizer - false
This means all is well. Thefalse points to the fact that no other applications are accessing these particular drivers. If you still don't have a sound, then you probably don't have a soundbank in your JRE folder. It gets confusing because you may have more than 1 JRE in your Programs Folder, and some may have a soundbank while others may not - Which JRE the application will use is not always clear, so it's easiest to copy a soundbank to all the JREs - see also the Before Downloading chapter for more on this. Luckily, the Java people have addressed this problem of multiple JREs with their latest version JRE 6. Another reason to go the whole hog and update to JRE6.

If the info window doesn't announce that it found a synth or sequencer, you have to work out why your system does not have these capabilities...

Ironically, you may have trouble when you're a developer. Developers tend to use the Java Development environment (JDK) for writing code, which comes with its own 'Runtime environment' (JRE). For some crazy reason, the JDK still has old sound libraries present, named sound.jar (if I remember correctly). These need to be deleted since they are a remnant from days gone by and interfere with sound manipulation.

back to index

Creating your own sessions: Overview

As mentioned previously, you can get away with just creating a session folder with one or more midi files, without scores. You also don't need to supply all the instruments (channels) in the midi files. The only rule being that the channels are properly allocated (see introduction). You still need to archive the session into a jar file. See more on that in the Archive the files. But for the sake of this writing, I just run through all the phases in the production of a complete session.

Steps that need to be taken to create your own sessions:

  1. Find or create a series of grooves in MIDI format, ideally not too long, with a common theme.
  2. Edit the MIDI files
  3. Create the score
  4. Edit the score
  5. Zip the score files and MIDI files into a jar file

Each of the listed stages requires its own software which I will elaborate on in the following sections.

back to index

Create MIDI files

My method is to play the grooves on a MIDI keyboard and record it using a software sequencer. The one I use is Cubase. Cubase Lite comes free with many applications. There are other software sequencers around that are free. You can alternatively enter the notes manually, which requires more work.

The following settings are required for each MIDI file for the application to work correctly:

Right Handchannel 1required
Left Hand channel 2required
Bass channel 3optional
Drums channel 10optional

Two points of note:

  1. It is better to quantize your MIDI files so that the loop settings start and stop on the right notes, otherwise notes may be lost when looping through sections. This will be at the cost of musicality, but this is a practice tool after all.
  2. When you save the MIDI file, and you have the option to set some settings, make sure not to add any unnecessary data, such as system exclusive data and event data, because we will need to edit those out later on.

back to index

Edit MIDI files

This is necessary mainly to clean up all the extra stuff that sequencer software tends to add to the MIDI file.

There is great SW that can help accomplish this editing: Mtx2Midi and Midi2Mtx.

Once you installed this sw, you can Right Click on any midi file and choose Convert to MTX to convert it to a text file which you can open with Notepad (or Notepad++, which I prefer). Once you edited this text file you can convert it back to MIDI with Right Clicking on the mtx file and choosing Convert to Midi. In Windows 7, you may need to select Open with first.

To be able to edit MIDI files you will need to have a good understanding of the MIDI protocol. It really is not very hard, this article gives a good overview of the MIDI format.

Here's an example of a simple MIDI file which contains just a few notes. The explanations in the right column were added by me and are not part of the file.

MFile 1 4 96 file header with following values:
  • format: One of three types.
    • 0 means contains single track
    • 1 means one or more simultaneaous tracks
    • 2 means one or more sequentially independent single-track patterns
  • numtracks: number of tracks
  • division: pulses (ticks) per quarter note resolution
MTrk start of track
0 TimeSig 4/4 24 8 at tick 0, the timesignature values are: (declared in the first track only):
  • time signature 4/4
  • 24 clocks per quarter note (standard)
  • 8 32nd notes in a midi quarter note
0 Tempo 500000 each quarter note is 500,000 microseconds long. Refered to as microtempo
  • To calculate bpm, use: (60 * 106)/value. Here, (60 * 106)/500000 = 120 bpm
  • To calculate Microsecs per quarter note, use (60 * 106)/value. Here (60 * 106)/120 = 500000 microsecs per quarter note
384 Meta TrkEnd meta information for the end of track: occurs at tick 384
TrkEnd end of track declaration
0 PrCh ch=1 p=5 program change event channel 1, program (also referred to as patch or instrument) 5
192 On ch=1 n=76 v=32 at click 192 we have a note on event on channel1, note 76, volume of 32
384 On ch=1 n=76 v=0 at click 384, the same note's volume is set to 0. This is used instead of a note off event, which essentially does the same thing
384 Meta TrkEnd
0 PrCh ch=2 p=46
96 On ch=2 n=67 v=64
384 On ch=2 n=67 v=0
384 Meta TrkEnd
0 PrCh ch=3 p=70
0 On ch=3 n=48 v=96
0 On ch=3 n=60 v=96
384 On ch=3 n=48 v=0
384 On ch=3 n=60 v=0
384 Meta TrkEnd

Here's a snapshot of one of my MIDI files (without the actual note data). Note that this one hasn't got a bass track.

MFile 1 6 480				// 6 tracks, one of which is a header track
0 Meta SeqName "groove01"
0 Tempo 600000
0 TimeSig 4/4 24 8
0 Meta TrkEnd

0 Meta TrkName "RH"
0 PrCh ch=1 p=0
240 On ch=1 n=58 v=99
. . .
15360 Meta TrkEnd

0 Meta TrkName "LH"
0 PrCh ch=2 p=0
241 On ch=2 n=31 v=0
. . .
15360 Meta TrkEnd

0 Meta TrkName "Rhythm"
0 PrCh ch=10 p=127
0 On ch=10 n=35 v=111
. . .
15360 Meta TrkEnd

Try to edit your MIDI files so they look like this. This is to avoid any unnecessary conflicts in the software. Things you need to look out for:

  1. Watch the Meta TrkEnd, lots of sequencer SW doesn't snap to the end of the track, which affects the timing when it is looping. In this example, all Meta TrkEnd values must have the value 15360 in the above example for the following reason: First of all, I know that the groove is 8 bars long (not directly given in the file). The first line indicates that we have a 480 ticks per quarter note resolution. A few lines up we read that we have a 4/4 time signature, which means that each bar has 4 quarter notes. So knowing this, we should have a total of 480 * 8 * 4 = 15360 ticks.
  2. Remove any duplication and Program Change events.
  3. Remove all track volume settings (not the individual note volume settings).

back to index

Create the Score

The score is just an image, so technically any image that stays within the limits of W=700 and H=600 should do as long as it is in the PNG format. Creating a good score requires adjustment of many variables, so it takes some experience to produce good (i.e. easy to read) scores.

My scores are produced using Cubase, however, I don't think this is possible in the Lite version. Again there's free SW for this, Jonathon Wilson (the creator of many of the funk grooves) swears by Lilypond. In order to make the score easy to read, I like to group rests with notes, that is, treat the rest as if it was a note. And group notes according to the number of beats in a bar. In a 4/4 tune I will aim for 2 groups in each bar (on the 1st and 3rd beats) and I use ties when note lengths cross over these groups.

Export the score files in any format, but they must have the same name as their correspending MIDI files, otherwise the Piano groove Tutor will fail.

back to index

Edit the Score

The score, once exported needs to be edited so it can be displayed in the Piano groove Tutor

My favourite free photoshop-like SW is 'Gimp' which I use a lot. Just resize the scores so they are within the application size constraints, which are:
size: 750 x 600
format: png
background: transparent

The general procedure in Gimp is as follows

  • Open score
  • Add title (size 40)
  • Crop (use rectangle tool and go image → crop to selection)
  • Make transparent (Select colors → Color to alpha for each layer)
  • Scale image (Image → resize)
  • Save as PNG

back to index

Archive the files

By now each groove should have a MIDI file and corresponding PNG file which is equally named. All the grooves of a session should reside in a folder that bears the name of the session. It is this name that will be displayed.

All that remains doing now is to zip these files into one file using a zip tool. The Java version of zip is jar (java archive).

The jar file is nothing but a zip archive, it uses the same compression as winzip (See this article). Apparently you can just zip a folder and then rename it with a jar extension as long as you don't add encryption to password protect your folder. However, I tried this with 3 applications: Window 7's zip facility, winzip, and 7z. After renaming the zipped files with the jar extension, they failed to load in the Piano Groove Tutor. This is unfortunate since using the jar tool requires you to download a 67 MB file, called the java JDK (Java Development Kit) - which is a package for Java software developers.

Go to the Oracle website to download the latest java JDK for your system. You'll get a file named jdk-6u23-windows-x64.exe or similar. Install it, noting the folder it installs to. After installation, navigate to

<installation folder> → jdk1.6.0_23 → bin (or similar).

In this bin folder you will see the jar tool jar.exe. We now need to tell the operating system that this tool is available, which means you need to make it available in the system environment variables:

Control panel → System → Advanced system settings → environment variables

In the system variables section, highlight the line 'path ...' → edit. Add the following line at the end (replacing the path and file name with yours of course):

;C:\Program Files\Java\jdk1.6.0_23\bin

This will tell Windows to look in that folder whenever a tool is required. Now we can use the jar tool in the command prompt. There is a nice roundabout way of getting the command prompt right were you want it: Create a text file with Notepad or similar, write 2 lines like so:


Rename the file to something like cmd.bat and you have now created one of the simplest batch files. Copy this file to the folder where you want to use the jar tool. That is, the folder that shows all your session folders. Assuming you have a folder named My Session, then type the following in the command prompt:

jar cfvM "My Session.jar" "My Session"

Don't forget the double quotation marks, they are necessary if the file name contains spaces. Press <Enter> and at long last, there is your jar file.

If you do want to use the Java jar tool for de-archiving etc, here are some notes I use:

cf create a jar
tf view contents
xf extract contents
v verbose
M without a manifest file
" " use for filenames with spaces
jar session files: compresses salsa folder into salsa.jar (remove thumb files first + order alphabetically) compress - verbose - 
jar cfvM "my jarfile.jar" "some File" 

read a jar file to check
jar tvf jarfile.jar

extract a file (note use of quotation marks to handle spaces)
jar xf "salsa tunes.jar" META-INF/MANIFEST.MF

look at extracted file

Once you have the jar file, copy it to the Piano Groove Tutor's sessions folder, and the application should recognize it at next startup.

It's quite a long-winded process, but once you've installed and used all the software to create the first session, creating the next one will be much easier.

back to index