Rosegarden Device File (.rgd) Developer's Guide

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

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.

When working on .rgd files, it's nice to have the following “rgless” script handy. It will decompress and display the xml for you:

#!/bin/sh
 
# Display an rg/rgd file using less...
 
cp "$1" "$1.xml.gz"
gzip -d "$1.xml.gz"
less "$1.xml"
rm "$1.xml"

Be sure to put this script someplace it can be found by bash. E.g. ~/bin.

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
$ rgless GM.rgd

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

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

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

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

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

<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>

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 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.

<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:

<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>

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

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 rgdgrep (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 (msb/lsb/pc) 121/0/0 Piano 1 121/0/1 Guitar 1 (Note that there is no PC 2 in this bank!)

Second Bank (variations) 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.

The following rgdgrep script can be used to search all the installed .rgd files:

#!/bin/bash
 
# Search for a string in the installed rgd files.
 
for rgdfile in ~/.local/share/rosegarden/library/*.rgd
do
    shortname=${rgdfile##*/}
    gzip -dc "$rgdfile" | grep --label "$shortname" -H -i $1
done

• Device owner's manual should have the information you need.
• Find a similar .rgd file and use that as a starting point.
• txt2rgd.py
• ins2rgd.pl

• 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.

#!/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"

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.

• Basic process
• Limitations

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.

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

An older guide is also available here:

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

TODO: Attach a tar.gz file with all the scripts.