======Documentation: File Formats======
This page describes the file formats used by the DrumGizmo engine. For ease of use we have implemented everything using xml. The main files are the drum kit files, the instrument files and the midi map files. These are described in detail below.

=====New file format (version 0.9.17 and up)=====
====Drumkit xml format====
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit samplerate="48000" version="2.1.0">
  <metadata>
    <version>1.2.3</version>
    <title>Test Kit</title>
    <logo src="LogoFile.png"/>
    <description>This is the description of the drumkit</description>
    <license>Creative Commons</license>
    <notes>These are general notes concerning anything of relevance for this particular version of the drumkit</notes>
    <author>Author of the drumkit</author>
    <email>author@email.org</email>
    <website>http://www.drumgizmo.org</website>
    <image src="DrumkitImage.png" map="DrumkitImageClickMap.png">
      <clickmap colour="ff08a2" instrument="China"/>
      <clickmap colour="a218d7" instrument="HihatClosed"/>
    </image>
  </metadata>
  <channels>
   <channel name="AmbL">
     <title>Ambience left</title>
   </channel>
   <channel name="AmbR">
     <title>Ambience right</title>
   </channel>
   <channel name="Hihat"/>
   <channel name="KdrumL">
     <title>KickDrum left</title>
   </channel>
   <channel name="KdrumR">
     <title>KickDrum right</title>
   </channel>
   <channel name="OHL">
     <title>Overhead left</title>
   </channel>
   <channel name="OHR">
     <title>Overhead right</title>
   </channel>
   <channel name="RideL">
     <title>Ride left</title>
   </channel>
   <channel name="RideR">
     <title>Ride right</title>
   </channel>
   <channel name="Snare_bottom">
     <title>Snare bottom</title>
   </channel>
   <channel name="Snare_top">
     <title>Snare top</title>
   </channel>
   <channel name="Tom1"/>
   <channel name="Tom2"/>
   <channel name="Tom3"/>
   <channel name="Tom4">
     <title>Floor tom</title>
   </channel>
   <channel name="Trigger">
     <title>Kickdrum trigger</title>
   </channel>
  </channels>
  <instruments>
    <instrument name="China" file="China/China.xml">
      <channelmap in="AmbL" out="AmbL" main="true"/>
      <channelmap in="AmbR" out="AmbR" main="true"/>
      <channelmap in="Hihat" out="Hihat"/>
      <channelmap in="KdrumL" out="KdrumL"/>
      <channelmap in="KdrumR" out="KdrumR"/>
      <channelmap in="OHL" out="OHL" main="true"/>
      <channelmap in="OHR" out="OHR" main="true"/>
      <channelmap in="RideL" out="RideL"/>
      <channelmap in="RideR" out="RideR"/>
      <channelmap in="Snare_bottom" out="Snare_bottom"/>
      <channelmap in="Snare_top" out="Snare_top"/>
      <channelmap in="Tom1" out="Tom1"/>
      <channelmap in="Tom2" out="Tom2"/>
      <channelmap in="Tom3" out="Tom3"/>
      <channelmap in="Tom4" out="Tom4"/>
      <channelmap in="Trigger" out="Trigger"/>
    </instrument>
    <instrument name="HihatClosed" group="hihat" file="HihatClosed/HihatClosed.xml">
      <chokes>
        <choke instrument="HihatFullyOpen" choketime="100"/>
        <choke instrument="HihatHalfOpen"/>
      </chokes>
      <channelmap in="AmbL" out="AmbL" main="true"/>
      <channelmap in="AmbR" out="AmbR" main="true"/>
      <channelmap in="Hihat" out="Hihat" main="true"/>
      <channelmap in="KdrumL" out="KdrumL"/>
      <channelmap in="KdrumR" out="KdrumR"/>
      <channelmap in="OHL" out="OHL" main="true"/>
      <channelmap in="OHR" out="OHR" main="true"/>
      <channelmap in="RideL" out="RideL"/>
      <channelmap in="RideR" out="RideR"/>
      <channelmap in="Snare_bottom" out="Snare_bottom"/>
      <channelmap in="Snare_top" out="Snare_top"/>
      <channelmap in="Tom1" out="Tom1"/>
      <channelmap in="Tom2" out="Tom2"/>
      <channelmap in="Tom3" out="Tom3"/>
      <channelmap in="Tom4" out="Tom4"/>
      <channelmap in="Trigger" out="Trigger"/>
    </instrument>
  </instruments>
</drumkit>
</code>

Most of the format is self-explanatory. Following is a quick rundown of the things that might not seem so obvious.

===drumkit node===
The drumkit main node only has one attribute which is the version attribute. Use this to do version control of your kit over time. This must use the x.y.z versioning format.

//Bent: We should use the version attribute for file format versioning and add a version tag in the metadata section instead.//

===metadata node===
Explained in the code above. It's self-explanatory.

===defaults node===
Tells DG what the default settings of the DG knobs are. In future releases there will be "reset to default" buttons in the gui which will use these default values. This node is currently not finalized and can be ignored until it's implemented.

//Muldjord: I'm not sure this makes sense. Knobs will change over time, which will quickly outdate the format. We should probably deal with this using presets inside the gui instead.//

===channels node===
The channel nodes manage the available channels that DG will create when loading the drumkit. These are the actual output channels that you will map in your DAW. You can have as many channels as you like. Each channel has metadata applied which currently is "title" and "microphone". These will be shown in the gui.

//Bent: We should think of a better name for the 'microphone' tag since not all audio sources are microphones (eg. trigger or other line signals). But maybe this information doesn't even make sense to store in the drumkit, if for example a cowbell recording is used from another recording setup, but mixed into the OH channels...//

//Muldjord: We'll change this to "source"//

===instruments node===
This node defines what instruments are used by the drumkit. "name" is a semantic name used by the midimap xml file. "file" defines what xml file to load for this particular instrument. "group" tells DG that this instrument is part of a group of instruments, for instance "hihat". Whenever a hit is detected on other instrument with a similar group name, DG will fade the other hit and begin playing the new one. This is very useful for close, open and pedal hihat hits.

The channelmap node connects the instrument channels to the DAW output channels. The "in" and "out" names DO NOT have to be the same. The "in" channel is defined withing the instrument.xml file itself. "bleed" tells what the default bleed for this instrument on this particular channel is supposed to be as default. A "reset to default" button in the DG ui will be introduced at some point, that resets all bleed to use these values". The "main" attribute tells DG that his channel is a main channel for this particular instrument. This is connected to the main bleed fader in DG which then can be set to never influence channels marked as main.

====Midimap xml format====
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<midimap>
  <map note="52" instr="China"/>
  <map note="49" instr="CrashL"/>
  <map note="57" instr="CrashR"/>
  <map note="42" instr="HihatClosed"/>
  <map note="46" instr="HihatOpen"/>
  <map note="35" instr="KdrumL"/>
  <map note="36" instr="KdrumR"/>
  <map note="59" instr="RideL"/>
  <map note="55" instr="RideLBell"/>
  <map note="51" instr="RideR"/>
  <map note="53" instr="RideRBell"/>
  <map note="38" instr="Snare"/>
  <map note="37" instr="SnareRest"/>
  <map note="48" instr="Tom1"/>
  <map note="47" instr="Tom2"/>
  <map note="45" instr="Tom3"/>
  <map note="41" instr="Tom4"/>
</midimap>
</code>

===midimap node===
The "note" attribute is the midi note value that will be connected. "instr" is the name defined in the "instrument" node in the drumkit xml file. A hit on this particular midi note will then play all channels of that particular instrument.

====Instrument xml format====
<code xml>
<?xml version='1.0' encoding='UTF-8'?>
<instrument version="2.0">
  <metadata>
    <title>The instrument title</title>
    <description>The instrument brand and further description</description>
    <license>GPL</license>
    <notes>These are general notes concerning anything of relevance for this particular version of the instrument</notes>
    <author>Author of the instrument</author>
    <email>author@email.org</email>
    <website>http://www.drumgizmo.org</website>
    <image filename="InstrumentImage.png"/>
  </metadata>
  <samples>
    <sample name="HihatClosed-1" power="0.0150941">
      <audiofile channel="AmbL" file="samples/1-HihatClosed.wav" filechannel="1"/>
      <audiofile channel="AmbR" file="samples/1-HihatClosed.wav" filechannel="2"/>
      <audiofile channel="Hihat" file="samples/1-HihatClosed.wav" filechannel="3"/>
      <audiofile channel="KdrumL" file="samples/1-HihatClosed.wav" filechannel="4"/>
      <audiofile channel="KdrumR" file="samples/1-HihatClosed.wav" filechannel="5"/>
      <audiofile channel="OHL" file="samples/1-HihatClosed.wav" filechannel="6"/>
      <audiofile channel="OHR" file="samples/1-HihatClosed.wav" filechannel="7"/>
      <audiofile channel="RideL" file="samples/1-HihatClosed.wav" filechannel="8"/>
      <audiofile channel="RideR" file="samples/1-HihatClosed.wav" filechannel="9"/>
      <audiofile channel="Snare_bottom" file="samples/1-HihatClosed.wav" filechannel="10"/>
      <audiofile channel="Snare_top" file="samples/1-HihatClosed.wav" filechannel="11"/>
      <audiofile channel="Tom1" file="samples/1-HihatClosed.wav" filechannel="12"/>
      <audiofile channel="Tom2" file="samples/1-HihatClosed.wav" filechannel="13"/>
      <audiofile channel="Tom3" file="samples/1-HihatClosed.wav" filechannel="14"/>
      <audiofile channel="Tom4" file="samples/1-HihatClosed.wav" filechannel="15"/>
      <audiofile channel="Trigger" file="samples/1-HihatClosed.wav" filechannel="16"/>
    </sample>
  </samples>
</instrument>
</code>

This file contains the complete description of one instrument.

===instrument node===
Contains the instrument "version" attribute. Must use the x.y format.

===metadata===
Self-explanatory.

===samples node===
"name" is a unique identifier for this particular sample/hit. "power" is an arbitrary attribute telling DG what power this particular hit/sample has in relation to the power attribute for the other hits defined in this file.

===audiofile node===
"channel" is the name used in the drumkit xml file to connect the instrument channel to the DG output channel. "file" tells what wav file to use. "filechannel" tells what channel inside that wav to use.

=====Drumkit xml format (versions before 0.9.17)=====
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit name="Test kit" description="This is were the description of the kit goes">
  <channels>
   <channel name="AmbL"/>
   <channel name="AmbR"/>
   <channel name="Hihat"/>
   <channel name="KdrumL"/>
   <channel name="KdrumR"/>
   <channel name="OHL"/>
   <channel name="OHR"/>
   <channel name="RideL"/>
   <channel name="RideR"/>
   <channel name="Snare_bottom"/>
   <channel name="Snare_top"/>
   <channel name="Tom1"/>
   <channel name="Tom2"/>
   <channel name="Tom3"/>
   <channel name="Tom4"/>
   <channel name="Trigger"/>
  </channels>
  <instruments>
    <instrument name="Hihat" group="hihat" file="Hihat/Hihat.xml">
      <channelmap in="AmbL-hihat" out="AmbL"/>
      <channelmap in="AmbR-hihat" out="AmbR"/>
      <channelmap in="Hihat" out="Hihat"/>
      <channelmap in="KdrumL" out="KdrumL"/>
      <channelmap in="KdrumR" out="KdrumR"/>
      <channelmap in="OHL" out="OHL"/>
      <channelmap in="OHR" out="OHR"/>
      <channelmap in="RideL" out="RideL"/>
      <channelmap in="RideR" out="RideR"/>
      <channelmap in="Snare_bottom" out="Snare_bottom"/>
      <channelmap in="Snare_top" out="Snare_top"/>
      <channelmap in="Tom1" out="Tom1"/>
      <channelmap in="Tom2" out="Tom2"/>
      <channelmap in="Tom3" out="Tom3"/>
      <channelmap in="Tom4" out="Tom4"/>
      <channelmap in="Trigger" out="Trigger"/>
    </instrument>
  </instruments>
</drumkit>
</code>
This example defines 16 output channels. It then loads the instrument contained in "Hihat/Hihat.xml" and maps the instrument output channels to the drumkit output channels. The instrument and drumkit output channels DO NOT need to be the same (in this case they are though). This makes it possible to merge instruments from physically different drumkits into one drumkit configuration.
The name and description attributes are not currently in use, but are useful for people editing the files.
The "group" attribute in the instrument node is used to bind several instruments into a group. For instance you can have "open hihat" and "closed hihat" being part of the group "hihat". The only effect this has is that whenever a closed hihat hit is played just after an open hihat hit, it will quickly fade the open hihat hit while play the closed hihat hit.

====Instrument xml format====
<code xml>
<?xml version='1.0' encoding='UTF-8'?>
<instrument version="2.0" name="HihatClosed">
  <samples>
    <sample name="HihatClosed-1" power="0.0150941">
      <audiofile channel="AmbL-hihat" file="samples/1-HihatClosed.wav" filechannel="1"/>
      <audiofile channel="AmbR-hihat" file="samples/1-HihatClosed.wav" filechannel="2"/>
      <audiofile channel="Hihat" file="samples/1-HihatClosed.wav" filechannel="3"/>
      <audiofile channel="KdrumL" file="samples/1-HihatClosed.wav" filechannel="4"/>
      <audiofile channel="KdrumR" file="samples/1-HihatClosed.wav" filechannel="5"/>
      <audiofile channel="OHL" file="samples/1-HihatClosed.wav" filechannel="6"/>
      <audiofile channel="OHR" file="samples/1-HihatClosed.wav" filechannel="7"/>
      <audiofile channel="RideL" file="samples/1-HihatClosed.wav" filechannel="8"/>
      <audiofile channel="RideR" file="samples/1-HihatClosed.wav" filechannel="9"/>
      <audiofile channel="Snare_bottom" file="samples/1-HihatClosed.wav" filechannel="10"/>
      <audiofile channel="Snare_top" file="samples/1-HihatClosed.wav" filechannel="11"/>
      <audiofile channel="Tom1" file="samples/1-HihatClosed.wav" filechannel="12"/>
      <audiofile channel="Tom2" file="samples/1-HihatClosed.wav" filechannel="13"/>
      <audiofile channel="Tom3" file="samples/1-HihatClosed.wav" filechannel="14"/>
      <audiofile channel="Tom4" file="samples/1-HihatClosed.wav" filechannel="15"/>
      <audiofile channel="Trigger" file="samples/1-HihatClosed.wav" filechannel="16"/>
    </sample>
  </samples>
</instrument>
</code>

This file contains the complete description of one instrument.

===instrument node===
Contains the instrument "version" attribute. Must use the x.y format.

===samples node===
"name" is a unique identifier for this particular sample/hit. "power" is an arbitrary attribute telling DG what power this particular hit/sample has in relation to the power attribute for the other hits defined in this file.

===audiofile node===
"channel" is the name used in the drumkit xml file to connect the instrument channel to the DG output channel. "file" tells what wav file to use. "filechannel" tells what channel inside that wav to use.