====== Rosegarden Device File (.rgd) Developer's Guide ======

//Document is still in progress, but should be quite helpful in its current state.//

===== What is a Rosegarden Device (.rgd) File? =====

Rosegarden device files (*.rgd) describe the bank selects, program changes, controllers, and percussion keymapping(s) for a specific MIDI synthesizer.

They can be loaded via the Rosegarden Device Manager: Studio > Manage MIDI Devices > Banks... > Import...

Device files are stored in ~/.local/share/rosegarden/library.  The files themselves are in xml format, gzipped.

==== GM.rgd ====

The most commonly used device files are likely GM.rgd and its successor GM2.rgd.  These are good examples to use for reference when making your own rgd files.  Let's have a look at GM.rgd:

  $ cd ~/.local/share/rosegarden/library
  $ zless GM.rgd

There are three main kinds of tags: ''<bank>'', ''<controls>'', and ''<keymapping>''.

==== Bank Tags ====

''<bank>'' tags define the bank select (msb/lsb) and program changes for the sounds in that bank.  A simplified example from GM.rgd:

<code xml>
<bank name="General MIDI" msb="0" lsb="0">
    <program id="0" name="Acoustic Grand Piano" />
    <program id="1" name="Bright Acoustic Piano" />
</bank>
</code>

The ''<program>'' tags define the program changes (sounds) within a bank.

==== Controls Tags ====

''<controls>'' tags define the controllers that the device honors.  From GM.rgd:

<code xml>
<controls>
    <control name="Pan" type="controller" description="&lt;none&gt;"
             min="0" max="127" default="64" controllervalue="10"
             colourindex="2" ipbposition="0" />
    <control name="Chorus" type="controller" description="&lt;none&gt;"
             min="0" max="127" default="0" controllervalue="93"
             colourindex="3" ipbposition="1" />
    <control name="Volume" type="controller" description="&lt;none&gt;"
             min="0" max="127" default="100" controllervalue="7"
             colourindex="1" ipbposition="2" />
    <control name="Reverb" type="controller" description="&lt;none&gt;"
             min="0" max="127" default="0" controllervalue="91"
             colourindex="3" ipbposition="3" />
    <control name="Modulation" type="controller" description="&lt;none&gt;"
             min="0" max="127" default="0" controllervalue="1"
             colourindex="4" ipbposition="-1" />
    <control name="PitchBend" type="pitchbend" description="&lt;none&gt;"
             min="0" max="16383" default="8192" controllervalue="1"
             colourindex="4" ipbposition="-1" />
</controls>
</code>

The ''<control>'' tags define each controller.  The above set of six controllers will be in almost every .rgd file and should appear as above.

The colourindex values allow a selection from among 5 colors (see the "generalmap" colourmap from autoload.rg):

^ colourindex ^ Color           ^
| 0           | default (peach) |
| 1           | Red pastel      |
| 2           | Green pastel    |
| 3           | Orange pastel   |
| 4           | Yellow pastel   |

The ipbposition numbers should be as above for those controllers.  For all others, the numbers should be "-1".  This prevents them from appearing on the UI unless the user explicitly asks for them.  ipbposition values are organized from left to right and then top to bottom.  This table shows the organization along with the controllers that historically have occupied each position:

| 0 (pan)    | 1 (chorus) |
| 2 (volume) | 3 (reverb) |

==== Keymapping Tags ====

''<keymapping>'' tags define a percussion key mapping.  E.g. middle C (60) is a "High Bongo" in General MIDI.  A reduced example from GM.rgd:

<code xml>
<keymapping name="General MIDI Percussion" channel="9">
    <key number="35" name="Acoustic Bass Drum" />
    <key number="36" name="Bass Drum 1" />
    <key number="37" name="Side Stick" />
    <key number="38" name="Acoustic Snare" />
    <key number="39" name="Hand Clap" />
</keymappping>
</code>

The ''<key>'' tags define each key and what drum sound it makes.  Note that 60 is middle C.

==== Variations ====

If your synth implements variations across bank selects (like General MIDI 2), consider using variations mode.  The ''<device>'' tag's "variation" attribute can be set to MSB or LSB based on which part of the bank select number changes for the variations.

To find some examples, use zgrep (see below) to search the device library for variation="lsb" or variation="msb".

Warning: For variations mode to work, every PC that has variations must be present in the first bank.  Here's an example that will not work:

First Bank:

^ BS MSB ^ BS LSB ^ PC ^ Patch Name ^
| 121    | 0      | 0  | Piano 1    |
| 121    | 0      | 1  | Guitar 1   |

(Note that there is no PC 2 in the first bank!)

Second Bank, variation 1, (variation="lsb"):

^ BS MSB ^ BS LSB ^ PC ^ Patch Name   ^
| 121    | 1      | 0  | Piano 2      |
| 121    | 1      | 1  | Guitar 2     |
| 121    | 1      | 2  | Violin (!!!) |

That Violin sound in the second bank will never show up in variations mode because there is no Program Change 2 in the first bank.

==== Searching the Device Library ====

Use the zgrep command to search all the installed .rgd files:

  $ zgrep Expression ~/.local/share/rosegarden/library/*.rgd

===== Starting from Scratch =====

  * Device owner's manual should have the information you need.

  * Find a similar .rgd file and use that as a starting point.

  * [[https://sourceforge.net/p/rosegarden/git/ci/master/tree/scripts/txt2rgd.py|txt2rgd.py]] - Script to convert a text file with bank selects, program changes, and voice names into an .rgd file.

  * [[https://sourceforge.net/p/rosegarden/git/ci/master/tree/scripts/ins2rgd.pl|ins2rgd.pl]] - Script to convert a Cakewalk .ins instrument file into an .rgd file.

===== Making changes =====

  * copy the file to a workarea

Here's an ''rgedit'' script that I use to make editing .rgd (and .rg) files a little less painful.

<file bash>
#!/bin/bash

# Edit an rg/rgd file...
# Show a diff after editing is complete.

cp "$1" "$1.xml.gz"
gzip -d "$1.xml.gz"

# Save for the diff.
cp "$1.xml" "$1.xml.before"

$EDITOR "$1.xml"

# diff

diff -u --color=always "$1.xml.before" "$1.xml"

if [ $? = "0" ]; then
    echo No changes...
    rm "$1.xml.before"
    rm "$1.xml"
    exit
fi

rm "$1.xml.before"

gzip "$1.xml"

mv -f "$1" "$1.original"
mv "$1.xml.gz" "$1"
</file>

When you are ready to test, install your .rgd file by copying it to the Rosegarden library:

  $ cp device.rgd ~/.local/share/rosegarden/library

Now the Device Manager (Studio > Manage MIDI Devices) will find it.

===== Editing with the GUI =====

  * The bank/program editor is built into the "Manage MIDI Banks and Programs" dialog.  (Studio > Manage MIDI Devices > Banks...)
  * The Key Mapping editor is there as well.  Use the "Add Key Mapping" button to create a new key mapping, and select it in the tree to edit it.
  * The controller editor is built into the Manage Controllers dialog.  (Studio > Manage MIDI Devices > Controllers...)
  * Loading and saving of everything (banks, program changes, keymaps, and controllers) is done via the Import... and Export... buttons on the "Manage MIDI Banks and Programs" dialog.

  * Advantages: Easy to experiment.

  * Limitations: Doesn't allow editing of all the elements.

===== Checklist =====

Before submission, be sure to go through the following checklist:

  * Make sure the ''<librarian>'' tag has your name and contact info.
  * Remove any ''<metronome>'' tags.
  * Remove any ''<instrument> ... </instrument>'' tags.
  * Make sure the Expression control's default="127".
  * Make sure the ''<device>'' tag's name is set to the name of the synth.
  * Make sure the ''<device>'' tag's connection="".
  * Sanity check importing the .rgd file and make sure everything is there.

===== Submission =====

Send your device files to our user mailing list for inclusion in the next version of Rosegarden:

https://sourceforge.net/projects/rosegarden/lists/rosegarden-user

===== Utilities =====

//TODO: Get all the scripts into the source code scripts directory and link to them.  See txt2rgd.py above.//

===== References =====

An older guide is also available here:

https://www.rosegardenmusic.com/resources/documents/rgd-HOWTO.shtml