Documentation

Drum package specification (version 2.1)

This document describes how one can create a drum package for DrumKit. This process requires some basic understanding of XML.

1. Overview

A drum package consists in a bunch of .xml files, some images and some sound files.
To be imported, these resources need to be packed in an uncompressed .tar file.

2. The images

The application recognizes most image formats that are supported by the Windows operating system natively. The recommended format is .png, which allows transparency.

Two images are required for each drum, the second being an image of how the drum looks like when hit. Images may be reused, just as they are reused in the default package.

3. The sounds

Sounds must be in a WAVE (.wav) format. All the sounds provided in one package must have the same sample rate, the same number of channels, and the same bits per sample, otherwise it will not work.

4. The manifest (drumkit.xml)

The most important file that needs to exist in the drum package is the manifest. This file contains basic information about the drumkit, as well as the definitions of all the drums. A package missing this file will fail to import.

Structure:

• drumkit: Root element
• name: The name of the drumkit. Must be unique, otherwise the package will fail to import.
• description: The description of the drumkit, optional.
• configfile: The name of a file which will contain the drum configurations.
• layoutfile: The name of a file which will contain the layouts.
• drums: A list of the drums.
• drum: Defines a new drum. The id attribute is mandatory, and is used to identify a drum. It will also be used in the configuration and layout files.
• name: The name of the drum, displayed in the editor and drum manager.
• image: The name (and path) of an image of the drum.
• imagePressed: The name (and path) of an image which will be displayed when the drum is hit.
• sounds: A list of sounds which are linked to this drum.
• sound: Defines a new sound. The intensity attribute¹ is mandatory. 

Notes: 

¹Version 2.1 only plays the sound with the intensity 0, so only one sound can be added for a drum.

Sample code:

<?xml version="1.0" encoding="UTF-8" ?> 
<drumkit>
    <name>My drumkit</name>
    <description>I created this drumkit myself!</description>
    <configfile>config.xml</configfile>
    <layoutfile>layout.xml</layoutfile>
    
    <drums>
        <drum id="kick">
            <name>Kick</name>
            <image>Images/kick.png</image>
            <imagePressed>Images/kickPressed.png</imagePressed>
            <sounds>
                <sound intensity="0">Sounds/Kick.wav</sound>
            </sounds>
        </drum>
    </drums>
</drumkit>

5. The configuration file

The configuration file contains the user's preferences for each drum. The drum package must contain a default configuration file, but it is not mandatory for each drum to contain a configuration entry. In other words, the minimum configuration file would have an empty <drums /> element.

Structure

• drumkitConfig: The root element.
• drums: A list of drum configurations.
• drumConfig: Defines a new drum configuration. The targetId attribute is mandatory, and it specifies which drum the configuration applies to.
• enabled: If disabled, the drum will be hidden. Possible values: true, false.
• volume¹: Either a number between 0 and 1 if volumeL and volumeR are the same, or NaN if the two are different.
• volumeL¹: Volume on the left speaker, a number between 0 and 1.
• volumeR¹: Volume on the right speaker, a number between 0 and 1.
• vkey: Either the scancode of the key, or the name. Valid names can be found here. 

Notes:

¹Version 2.1 does not support this feature, so the value is ignored.

Sample:

<?xml version="1.0"?>
<drumkitConfig>
  <drums>
    <drumConfig targetId="kick">
      <enabled>true</enabled>
      <volume>1</volume>
      <volumeL>1</volumeL>
      <volumeR>1</volumeR>
      <vkey>A</vkey>
    </drumConfig>
  </drums>
</drumkitConfig>

6. The layouts file

The layouts file describes how the drums will be displayed on the screen. At least one layout must be provided.

Structure:

• drumkitLayoutCollection: The root element.
• items: A list of layouts.
• drumkitLayout: Defines a new layout.
• name: The name of the layout.
• targetView: The views this layout supports. Possible values are: None, All, Portrait, Landscape, Filled, Snapped. Values can also be combined like this: Portrait|Snapped.
• isDefault: Whether this layout is active or not. Possible values are: true, false. If two different layouts have the same target view, the one having this property true will be picked.
• drums: A list of drum layouts. ALL drums must have a drum layout attached.
• drumLayout: Defines a new drum layout. The targetId attribute is mandatory.
• size: the size relative to the screen width. The final size will be a square with the width and height equal to size * screen_width.
• x: the x coordinate, relative to the screen width.
• y: the y coordinate, relative to the screen height.
• zindex: integer value, describes how the drums are overlapped. A higher value will make that drum be displayed in front. If two drums have the same zindex, their order is the order in the manifest.
• angle: the clockwise rotation in degrees.

Sample:

<?xml version="1.0"?>
<drumkitLayoutCollection>
  <items>
    <drumkitLayout>
      <name>Standard layout</name>
      <targetView>All</targetView>
      <isDefault>true</isDefault>
      <drums>
        <drumLayout targetId="kick">
          <size>0.3</size>
          <x>0.41</x>
          <y>0.2</y>
          <zindex>0</zindex>
          <angle>0</angle>
        </drumLayout> 
      </drums>
    </drumkitLayout>
  </items>
</drumkitLayoutCollection>