Getting the program

You only need one file: jTrapKATEditor.jar.

Installing the program

The program itself needs no installation. However, it depends on Java Runtime 1.8, which is usually already installed but, if not, is available from Oracle, at http://java.com/en/download/.

Running the program

Once you have downloaded the program, running it should just be a matter of double-clicking the jTrapKATEditor.jar file. If installed correctly, the Java Runtime should execute the program.

The program can be run from the command line using the following command (assuming the java executable is in your PATH): java -jar jTrapKATEditor.jar.

Setting up a new kit layout

Imagine you have a new sound source for your TrapKAT and the layout is similar but not exactly the same as another kit you already have mapped up. Let us assume you have no reason to change the sound source to match the TrapKAT and that the TrapKAT has a spare user kit.

Here are the steps you will need to follow to set up a new kit layout:

1. Get the current TrapKAT All Memory Dump onto your computer.
2. Edit the dump with jTrapKATEditor.jar to copy the similar kit and make changes.
3. Save the edited dump.
4. Send the updated dump back to the TrapKAT.

The first and last points are outside the scope of what jTrapKATEditor offers and differ substantially depending on whether you are running on Windows, MacOS or Linux.

For Windows, I still recommend MIDI-OX for receiving and sending MIDI System Exclusive dumps such as these. Receiving the dump using MIDI-OX is straight forward and no special settings are needed. The transmit settings for sending the dump - which are "delicate" due to timing issues - are given at the bottom of the jTrapKATEditor.jar main window.

Load the dump

Once you have got the TrapKAT All Memory Dump onto your computer, run jTrapKATEditor.jar. It starts up with some rather useless default values but we are going to ignore those and load the dump. You can use the File menu, Open... entry or press Ctrl/Cmd O. This will bring up the following dialog box (or appropriate windowing system-specific flavour).

You will notice that it filters for Sysex files. It expects an extentions of "syx" to be used. If you did not save the received dump with that extension, I would recommend doing so.

I also very strongly recommend having a separate "working copy" file that you use for testing new and changed layouts.

Select the file you saved and press Enter or click Open.

Copy one kit to another

The main display should now look similar to the following.

Note that the Kits & Pads main tab is selected as is the Pad Details subsidiary tab. As this was a Version 4 dump (indicated in the title bar as "(V4)" after the file name), the More Slots tab is available as well as Kit Details. For this example, we will leave the tabs alone.

Just below the Kits & Pads tab itself is the Select Kit drop-down. Select the base kit that is going to be copied.

The pads now show the values for this newly selected kit, including the kit name. We want to copy this kit to one of the spare ("Demo Kit #XX") entries. For this, select Edit->Copy Kit. This places a copy of the kit on the system clip board, so it can be pasted elsewhere (even after closing the program).

Next we need to switch kits and do just that. So, use the Select Kit drop-down to switch to the free kit and then Edit->Paste Kit.... This pops up and dialog asking for confirmation of the action, as shown (with appropriate names and numbers).

Select Yes and the kit is overwritten with the copy. Note that the kit number is held for each kit - if you send a single kit to the TrapKAT, it uses this to know which user kit to write into.

Notice the title bar now has "[*]" at the end - indicating the file being edited has been altered but not saved.

Change the kit layout

We chose the source kit as "similar to but not the same as" what we need. The things we want to alter are as follows.

• The kit name
• The way the hi-hat works
• The pads for china and ride
• The note for the kick drum

Set up the new hi-hat

For this example, assume the old kit only had "closed" and "bell" hi-hat sounds, these mapped to pads 1 and 11. For the new kit, we now have "closed" and "variable (CC4)" hi-hat sounds we want to trigger from pad 1 and the "bell" sound is unchanged. This means pad 1 needs to be marked as a hi-hat pad and to trigger two notes: one for when the hi-hat pedal is closed and one for when the hi-hat pedal is between (nearly) closed and fully open. We will assume the kit was already set to use a variable CC4 hi-hat pedal. The steps are as follows:

1. Set pad 1 to be a hi-hat pad
2. Select pad 1
3. Set slot 2 to be the variable note trigger

Which pads are considered hi-hat pads by the TrapKAT is an interesting subject examined in detail later. For now, look near the middle of the window, where you should see a set of four drop-downs. Hovering with the mouse gets a short tooltip.

Use the first box (although that is not important) to select pad 1.

Now use the Select Pad drop-down to select pad 1 (if it is not already selected). Notice that the pad is marked "Edited". (Note also the Flags for the pad now have flag 7 checked.)

Finally, we have to add the "between (nearly) closed and fully open" note. For a hi-hat pad, odd numbered slots represent closed sounds and even are when the pedal is not fully closed. So the new note needs to go into slot 2. If you click the slot 2 dropdown, you will see the following.

For this example, we do not need to use the special values, just enter the note. I use note numbers - they are explicit and do not have octave offset confusion. I will use note 66 in this example, so that gets entered in the text box.

And that is the hi-hat done.

Set the kick note

Similarly to setting the hi-hat second slot, this is just a matter of entering the required note in the Bass pad text box.

Save the edited kit

Now that the changes have been made, they can be saved to disk. You can either save the entire All Memory Dump or you can save just the kit that you have been working on. As we were working on an All Memory Dump, saving as a kit would need a name specified. For testing a single kit, it is probably worth doing as the kit sends to the TrapKAT more easily as it is smaller.

The Save File dialog will appear with a suggested filename based on the kit name.

Having saved to a new single kit file, that file becomes the current file being edited. The shortcut for save - Ctrl/Cmd S - shown against "Save All Memory" above will then be against "Save Current Kit".

Getting Help

Staying up to date

The first thing to do if you hit a snag is make sure you can reproduce the problem using the latest version of the program. You can make sure you have the latest version using Help->Check For Update.... If this says "No update applicable was found." then you are up to date. Otherwise, you will be offered the chance to go to the project site to read about the latest version. From there, you can navigate back to the download page.

If you have a permanent internet connection on the computer you run the editor on, you are strongly recommended to use the automatic update checker. This is toggled on and off by Help->Check Automatically. The program will check automatically at most once every day. If it finds an update available, it will display the update available notice shown above.

Asking questions and reporting issues

The most effective way to get an answer to a problem is to post in the AlternateMode forum in the thread for this editor. Always look under Help->About to get the version details and include these details in your post. This ensures anyone looking at your post in future knows which version it relates to.

Try to explain the steps you have taken with the TrapKAT and with the TrapKAT editor software clearly, saying what you expected to happen and what actually happened. I need to be able to reproduce the problem with my set up if I am to have any hope of either answering a question or fixing a bug, so do please take the time to explain clearly. (I do realise it takes some effort -- it took me days to pin down the last bug clearly enough I could fix it: in fact it turned into three related bugs, which was why it was so confusing!)

Note that I can, unfortunately, only test with a TrapKAT V4 now. However, I can explain to V3 users how to provide the details I would need to investigate a problem, should they have one. Just mention this when posting in the forum.

As the program is Open Source (see Help->Licence... or below for more), you always have the option of reading the code and trying to identify possible fixes or improvements yourself. The Github project page is the best place to find further information.

Program Configuration

There is little in the way of configuration visible to the user. The only option is how to display note values - Tools->Options->Display MIDI Notes, choosing from As Numbers (the MIDI note number), As Names (C3=60) or As Names (C4=60) (showing the note name with Middle C getting the indicated name).

In addition to the setting for automatic updates, mentioned earlier, the program stores two more values relating to the update process.

Last Update Time

This holds the time that the last automatic or manual update check was run. The value is displayed in Help->About, as shown above.

Last Ignored Version

This is used by the automatic update checker to avoid prompting for an ignored version. Checking manually bypasses this value and always prompts if it finds a newer version (but lets you ignore again, of course).

Finally, there are two further internal settings that aim to make life easier between runs of the program.

Current Working Directory

This tries to keep track of the last folder or directory which you used for a file operation, so it is what you are offered next time.

Window Location

This keeps track of the position of the window, so on start up the window appears where it was when you last closed the program.

All of the settings are held per user in a file called jTrapKATEditor.xml, the location of which is determined by the operating system. If something goes badly wrong and the program appears not to start, you can try renaming or deleting this file - check the program is really not running first, though.

Creating and Loading

The File menu allows you to create TrapKAT V3 and TrapKAT V4 dumps from scratch, using New (V3) or New (V4) respectively. You can also load complete memory dumps, global memory dumps and individual kit dumps, all using the Open menu item.

The only real use of New is to make using Open easier for global and kit dumps that you want to edit in isolation from an all memory dump.

Open prompts for the file to be opened and, after confirming with you that losing any unsaved changes that would be overwritten is okay, proceeds to load the file. For example, if you have edited kit values and load a global dump, you do not get prompted as no changes have been made to global memory. However, loading another kit dump for the edited kit would prompt.

Saving

The File menu allows you to write out your changes. You can choose to save back to the last opened file of the appropriate type or save the current kit, global memory or all memory to a specific file.

When you start the program or use one of the New menu options, the editor considers that it has no file currently being edited and you must choose where to save edits. When you Open, if no file is being edited or if the opened file is an all memory dump, the opened file becomes the current file. The current file, including the version and overall change state, is shown in the application title.

If the current file is a global dump and you load a kit file or vice versa, the editor considers that it has no specific file being edited, so you must choose what to save. If the current file is a kit dump and you load the same numbered kit, that kit becomes the current file. If the current file is a kit dump and you load a different numbered kit - either into the current kit or its own kit - the editor considers that it has no specific file being edited again. If you are editing an all memory dump, loading global or kit dumps does not change what the editor considers the current file (i.e. the all memory dump).

No current file being edited

Current file is all memory dump

Current file is global dump

Current file is kit dump

When you save a file, that file becomes the current file. All in all, this usually ends up being exactly what you'd expect...

Converting

The editor provides for converting between V3 and V4 dumps in both directions. This can be done in a number of ways.

If you have used New (V3) or loaded a V3 all memory dump with Open, then Tools->Convert... will offer to convert to V4. This is then considered a new V4 dump that has been edited.

If you have used New (V4) or loaded a V4 all memory dump with Open, then Tools->Convert... will offer to convert to V3. This is then considered a new V3 dump that has been edited.

If you have used New (V3) or loaded a V3 all memory dump with Open, and then open a V4 global or kit dump, the program will offer to convert this to V3 and then work as if a V3 global or kit dump had been loaded.

If you have used New (V4) or loaded a V4 all memory dump with Open, and then open a V3 global or kit dump, the program will offer to convert this to V4 and then work as if a V4 global or kit dump had been loaded.

Editing Kit Details

All kit editing is, as you would expect, done on the Kits & Pads tab. On the main part of the tab, however, the only details are the kit Name field and Hihat Pads panel, with everything else being found on the Kit Details sub-tab. Kits can also be copied, pasted and swapped around using the Edit menu items.

As with the editor as a whole, the major benefit when editing kits is seeing the information presented clearly on screen so you can get a better idea of how each kit is set up, rather than trying to work through and memorise the settings as you tap pads on the TrapKAT.

Kit Details tab (V3)

Kit Details tab (V4)

One significant purpose of the Kit Details sub-tab is to ensure all pads use the same settings for certain fields. This covers Curve, Gate, Channel, Min Velocity and Max Velocity. When the Various checkbox is unchecked, this indicates the kit value for that field will be used. Checked means various pad values apply.

The Foot Controller section allows the various parameters to be configured, with the Same as Chick checkbox telling the TrapKAT to use the channel number assigned to the Chick pad. In the screenshots above, as the Kit Channel is 10 and its Various checkbox is not checked, you know the Chick pad channel used will be 10 and thus 10 will also be used for the Foot Controller messages.

An enhanced feature on the TrapKAT V4 is the ability to specify more than one set of sound control values. Up to four sets of these MIDI messages can be sent when changing to a kit. TxmChn specifies the Channel of each of the MIDI messages in this section for the selection sound control set. To make any sense, the sound control sets should be sent on different channels, of course, or they will counteract each other. The Off checkbox determines which messages are sent. If you turn off Program Change, then neither MSB nor LSB will be sent either. The messages for each sound control will be sent in the order MSB, LSB, Program Change, Volume, from Sound Control 1 through to Sound Control 4.

In this first image, all four sound controls have all messages enabled.

In this second image, Sound Control 1 has Program Change off, Sound Control 2 has MSB and LSB off, Sound Control 3 has MSB and Volume off and Sound Control 4 has LSB and Volume off.

Depending on the target device, the result of sending or omitting any one of these is somewhat unpredictable - you must read the device documentation to be sure.

(On the TrapKAT V3, there seems some confusion over whether the Bank value is actually used. As such, I have left it in, although I believe it was only used prior to the V3 model.)

Editing Pad Details

As with kit editing, all pad editing is, unsurprisingly, done on the Kits & Pads tab. In this case the main part of the tab provides quick access to much of what is needed, specifically the first slot of each pad, with the Pad Details and (V4 only) More Slots sub-tabs providing less frequently accessed features. Pads can also be copied, pasted and swapped around using the Edit menu items.

Whilst the Hihat Pads panel is considered part of kit editing, it should noted that selecting or deselecting a pad as a hihat pad causes it's flag 7 to be set or unset. However, whilst setting its flag 7 directly does not update the kit's set of hihat pads, the TrapKAT still acts the same way - the flag is what is used. This means you can have more than four hihat pads in a kit!

(Note: the current editor behaviour is considered deficient. It is expected to act as follows: when flag 7 is set, if the pad is not in the set of hihat pads for the kit and there is a spare entry, it should be added, replacing any duplicate if need be; when flag 7 is cleared, if the pad is in the set of hihat pads for the kit, all instances should be removed from the set. This will mean that the set for the kit tracks the flag 7s until there are more pads flagged than fit the set.)

A big, big change in the V4 TrapKAT is in the power of pad chaining. Not only has the number of pad slots (the actions a pad can trigger depending on its Curve) increased from six to sixteen but striking one pad can now also trigger that pad and another through Link To.

Pad Details tab (V3)

Pad Details tab (V4)

More Slots tab (V4)

As noted earlier, Curve, Gate, Channel, Min Velocity and Max Velocity can be controlled at Kit level or Pad level. To enable the pad fields, the respective Kit Details tab Various checkbox must be checked.

Editing Global Details

Kits & Pads

Global

Menus

Warranty

Disclaimer of Warranty.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Licence

This program is distributed under the terms of the GNU General Public Licence version 3.

If you wish to see the full text of the licence, please visit http://www.fsf.org/licensing/licenses/gpl.html.

Source Code

The source code for this program is available to you for any purpose as permitted under the GNU General Public Licence version 3. To access the source code, please see https://github.com/pljones/jTrapKATEditor.