1.  Introduction

This mini-howto explains how to create a device definition file (in Rosegarden speak). Please refer to the Rosegarden tutorial paying particular attention to sections 2.4 to 2.10:

http://rosegarden.sourceforge.net/tutorial/

2.1.  Step One: Create The Program List

In order to create the *.rgd (device definition file) you need first to know what programs are available for your MIDI device, i.e. what instruments your keyboard or sound card can play.

The best source is probably your manual. Alternatively you may want to search on the Internet.

Programs are organized in banks. Within banks each program is specified by a MIDI program change number. Banks are designated by using two numbers: MSB (Most Significant Byte) and LSB (Least Significant Byte).

The MSB and LSB may take each any value between 0 and 127 (thus giving a total of 16384 banks). The program number takes values from 0 to 127 in the .rgd file but these will appear as 1 to 128 when viewed in your manual and also when they are loaded into Rosegarden's Bank editor.

The bank with MSB=0 and LSB=0 is well defined and known as GM (General Midi). The first program in this bank is the "Acoustic/Grand Piano", i.e. pianoforte and all 128 programs are well defined.

So we will tell Rosegarden about this program somewhat like:

• At MSB=0, LSB=0, Program=0 you find "Acoustic/Grand Piano"

The MIDI devices and software cares only about numbers, the name is for human consumption. I.e. you will use "Acoustic/Grand Piano" and the computer will understand "MSB=0, LSB=0, Program=0"

Rosegarden stores this information in the *.rgd file.

There are several ways you can tell Rosegarden what programs are available:

1. Use Rosegarden itself, via the Studio -> Manage MIDI Banks and Programs menu. However consider that only the GM bank contains already 128 programs and most keyboards or sound cards may well contain in excess of 500 programs. So entering by hand is a very tedious process.
2. Edit the *.rgd file directly: possible but not for the beginner (more about that below)
3. Create a list of programs and then convert it to the *.rgd format

We will take here the third approach.

First create a file containing the list of all programs. You can use either any text editor you feel comfortable with or any spreadsheet able to export in CSV (Comma Separated Values) format (any spreadsheet should be able to do this).

The format of the file is very simple:

1. Each line contains 5 parameters. Each parameter is separated from the next by either whitespace (spaces, tabs) and/or commas (only one comma between fields);
2. Empty lines are ignored;
3. You can add comments in any (reasonable) place. Comments start with the "#" character and continue to the end of line.

The list of the parameters is as follows:

1. The first one is for your reference, it will be ignored in the final output. You can put whatever you like except whitespaces and commas (because they are separators) and "#" because it will be taken as a comment. An example of what you can put in here is the program number, in order to keep track of what you have entered;
2. The second one is the MSB, it is a integer between 0 and 127;
3. The third one is the LSB, it is a integer between 0 and 127;
4. The fourth one is the program change number, it is an integer between 0 and 127 (remember, this is displayed as 1 to 128 in Rosegarden and in your manual);
5. And finally the last one is the program name. This field in particular may contain whitespace and/or commas but not "#";

You can optionally add comments after the fifth parameter.

Example:

    # This is a comment
       # This is another comment

    # GM Bank:
    first 0 0 1 Grand Piano   # this is the first program from the GM bank
    2 ,   0 0, 2 Bright Piano

If you want to save yourself some time and make sure that the data entered is correct you may proceed as follows:

• First obtain the manual in pdf format (it is available for the Yamaha keyboards from their site, other manufacturers may have it; check your CDs as well)
• Then try to see if you can copy & paste. You can do it from xpdf if the pdf allows it (sadly the Yamaha manuals don't!). Save the pastings into a text file.
• If you can't then you are down to a qute tedious process: use ps2ascii to convert to text.
• Finally edit the text to transform it into a format as described above.

It is still a tedious process but maybe less so than entering all programs from scratch. And very likey less error-prone.

For keyboards in particular: It is highly advisable to use the same program names as they appear on the LCD screen of the keyboard.

If you used a text processor make sure you save the file as plain text (ASCII); if you use a spreadsheet make sure you save in CVS format.

2.3.  Step Three: Verify And Adjust

Once you have generated the *.rgd file try to load it into Rosegarden, via Studio -> Manage MIDI Banks and Programs -> Import Banks

If it loads then you are basically done. It is likely that you may see some bank names as "000-112". This means the the script could not find a suitable name for the bank (the script tries to name the banks following the XG scheme).

You can rename that bank by double-clicking on its name. When you are done click on the "Export Bank" button.

Once you are done and satisfied consider sharing it. There may be other users with the same keyboard/soundcard and they shouldn't duplicate the work. You can mail it to one of the Rosegarden developers, to be added to the current library. Free software grows from community contributions.