DecentSampler: File Format Reference Guide

Document Version: 0.8.4

Table of Contents

• DecentSampler: File Format Reference Guide
  • Table of Contents
  • Introduction
  • The top-level <DecentSampler> element (required)
    • The <ui> element (optional)
      • The <tab> element
      • The <labeled-knob> element
    • The <groups> element (required)
      • The <group> element
      • The <sample> element
    • The <effects> element
      • The <effect> element
      • Low-pass filter
      • Reverb effect
  • Appendix A: The Color Format
  • Appendix B: The <binding> element
    • Controllable Parameters
    • Translation Modes
  • Appendix C: Boilerplate .dspreset File

Introduction

At its core each DecentSampler sample library consists of two things: a folder containing a bunch of assets like audio files and pictures, and a single text file (called a dspreset file) which describes how the engine should use all of those files. This reference document is a guide to creating dspreset files.

dspreset files are just XML files. As such, each one begins with an XML declaration:

<?xml version="1.0" encoding="UTF-8"?>

The top-level <DecentSampler> element (required)

At the top level of every dspreset file is a <DecentSampler> element. Every file must have one. Here is a list of attributes:

• minVersion (optional): This is the minimum version on which this preset is known to run. As of version 0.7.19, this information is not being used for anything, but the plan is to prevent users from loading presets that won’t actually work on their version of the engine.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<DecentSampler>
    <!-- More tags go here. :) -->
</DecentSampler>

Underneath the top-level <DecentSampler> element you can put any number of other elements, which are described below:

The <ui> element (optional)

The <ui> element is how you specify a user interface for your instrument. Each dspreset should have at most one <ui> element. There are several important attributes:

• bgImage (optional): A relative or absolutely path to a background image to use.
• bgColor (required): An eight digit hex value indicating the background color to be used for the background of the UI. This color will be drawn underneath any background image specified by bgimage.
• width (required): The width of your user interface. Recommended value: 812.
• height (required): The height of your user interface. Recommended value: 375.

Example:

<DecentSampler>
  <ui bgImage="background.png" width="812" height="375">
    <tab name="main">
      <labeled-knob x="560" y="0" label="Tone" type="float" minValue="60" maxValue="22000"
                    textColor="FF000000" value="22000.0" uid="y8AA4uuURh3">
        <binding type="effect" level="instrument" position="0" parameter="FX_FILTER_FREQUENCY"/>
      </labeled-knob>
    </tab>
  </ui>
</DecentSampler>

The <tab> element

The <tab> element lives underneath the <ui> element. This architecture was chosen because we may, at some point, we may add support for multiple tabs. At present it is only possible to have a single tab within DecentSampler instruments. As such, every UI must have at most one <tab> element.

Attributes:

• name (optional): An optional name to be associated with this tab. This is currently not displayed anywhere.

The <labeled-knob> element

The <labeled-knob> element lives underneath the <tab> element. These correspond to round radial dials with label above them. Every tab can have many <labeled-knob> elements underneath it. Attributes:

• x (optional): The x position of your control where (0,0) is the top-left corner
• y (optional): The y position of your control where (0,0) is the top-left corner
• label (optional): The actual text that should be displayed above the knob.
• minValue (optional): The minimum value of your control. Default: 0
• maxValue (optional): The maximum value of your control. Default: 1
• value (optional): The initial value of your control. Default: 0
• textColor (optional): An 8 digit hex value indicating the text color to be used for the label. See Appendix A for an explanation on these hex values.
• textSize (optional): A font size for the text label. Default: 12
• trackForegroundColor (optional): An 8 digit hex value indicating the foreground color to use for the knob track. See Appendix A for an explanation on these hex values.
• trackBackgroundColor (optional): An 8 digit hex value indicating the background color to use for the knob track. See Appendix A for an explanation on these hex values.
• uid (optional): This is an internally generated value. This can be ignored.
• width (required): The width in pixels of the knob + label.
• height (required): The height in pixels of the knob + label.

Example:

<DecentSampler>
  <ui>
    <tab>
      <labeled-knob x="560" y="0" label="Tone" type="float" minValue="60" maxValue="22000" textColor="FF000000" value="22000.0" uid="y8AA4uuURh3">
      <!-- Your <binding /> elements should go here -->
      </labeled-knob>
    </tab>
  </ui>
</DecentSampler>

To learn how to make knobs actually control parameters of your instrument, see “Appendix B: Bindings” section below.

The <groups> element (required)

Every dspreset file should have one and only one <groups> element. This is where you specify the samples that make up your sample library. This element lives right underneath the top-level <DecentSampler> element. The basic structure is this:

<DecentSampler>
    <groups>
        <group>
            <sample /> <!-- This is where -->
            <sample /> <!-- the samples   -->
            <sample /> <!-- get defined   -->
        </group>
    </groups>
</DecentSampler>

The <group> element

Samples live in groups. There can be many group elements under the <groups> element. It can be useful to sort your samples into groups in order to apply similar settings to them or to control them with a knob. The order of groups in a file matters insofar as bindings will often reference groups by using an index. The first group in a file is group 0, the second is group 1, etc.

The <sample> element

Underneath the <group> elements are <sample> elements. Each sample corresponds to a playable “zone” of your instrument. Attributes:

Looping

Amplitude Envelope

Each sample as its own ADSR amplitude envelope.

Round Robins

Round robins allow different samples to be played each time a zone is triggered. This is especially useful with sounds that have short attacks (such as drums), and is a great way to keep your sample libraries from sounding fake. In order for round robins to work, you must specify both a seqMode and a seqPosition for all samples. There are several round-robin modes:

• round_robin: This causes samples to be triggered sequentially according to their seqPosition values.
• random: This causes random samples to be chosen from within the group of samples. If there are more than two round robins, then the algorithm makes sure not to hit the same one twice in a row.
• true_random: This causes random samples to be chosen from within the group of samples.
• always: This just turns round robins off.

The <effects> element

Adding global, instrument-wide effects is easy: just add an <effects> element right below your top-level <DecentSampler> element.

The <effect> element

Within the <effects> you can have any number of <effect> elements. These specify parameters for each individual effect that you would like to have in your global effects change. There are currently only a handful effects available although more could definitely be added on request:

Low-pass filter

A 4-pole resonance filter

Example:

<DecentSampler>
  <effects>
    <effect type="lowpass_4pl" resonance="0.7" frequency="22000" />
  </effects>
</DecentSampler>

Attributes:

Reverb effect

Example:

<DecentSampler>
  <effects>
    <effect type="reverb" roomSize="" damping="" wetLevel="" />
  </effects>
</DecentSampler>

Attributes:

Appendix A: The Color Format

Colors are represented throughout the dspreset files using an 8-digit ARGB color format. These are identical to web color hex codes except with an additional 2-digit hex number in front of them. The first two digits are a hexadecimal representation of alpha level with 00 being fully transparent, 80 being 50% transparent, and FF being fully opaque.

Examples:

• Black (solid): FF000000
• Black (90% transparency): E6000000
• Red (solid): FFFF0000
• Red (50% transparency): 80FF0000
• Blue (solid): FF0000FF

Appendix B: The <binding> element

Adding a binding to a UI control tells the DecentSampler engine that it should take input from a source and use it to change values in another part of the engine. An example of this would be a knob which controls the volume of a group or a CC controller that changes an effect parameter.

In order to set up a binding for a specific source, create a <binding> element within the source element.

In this example, a labeled knob is controlling the volume of the first group of samples (group 0):

<DecentSampler>
  <ui>
    <tab>
      <labeled-knob x="420" y="100" label="RT" type="float" minValue="0" maxValue="1" value="0.3" textSize="20">
        <binding type="amp" level="group" position="0" parameter="AMP_VOLUME" translation="linear" translationOutputMin="0" translationOutputMax="1.0"  />
      </labeled-knob>
    </tab>
  </ui>
</DecentSampler>

Here’s a full list of parameters for the <binding> element:

Controllable Parameters

This is a list of parameters that can be used in conjunction with the <binding> element above.

Translation Modes

There are currently two binding translation modes: linear and table:

1. linear mode allows values that come in to be scaled up or down before they get passed along to the binding’s target. If you set your translation mode to linear you should also translationOutputMin and translationOutputMax.
2. table mode allows you to transform the binding’s input in a more complex fashion before it gets passed along to the binding’s target. If you set your translation mode to table you must define the translationTable parameter as well. This consists of a series of input-output pairs, separated by semi-colons.

Appendix C: Boilerplate .dspreset File

<?xml version="1.0" encoding="UTF-8"?>
<DecentSampler>
  <ui bgImage="background.png" width="812" height="375" layoutMode="relative"
      bgMode="top_left">
    <tab name="main">
      <labeled-knob x="560" y="0" label="Tone" type="float" minValue="60" maxValue="22000"
                    textColor="FF000000" value="22000.0" uid="y8AA4uuURh3">
        <binding type="effect" level="instrument" position="0" parameter="FX_FILTER_FREQUENCY"/>
      </labeled-knob>
      <labeled-knob x="655" y="0" label="Reverb" type="percent" minValue="0" maxValue="100"
                    textColor="FF000000" value="50.0" uid="lKv29kggDro">
        <binding type="effect" level="instrument" position="1" parameter="FX_REVERB_WET_LEVEL"
                 factor="0.01"/>
      </labeled-knob>
    </tab>
  </ui>
  <groups attack="0.000" decay="25" sustain="1.0" release="0.430" volume="-3dB">
    <group>
      <sample loNote="21" hiNote="21" rootNote="21" path="DefaultPiano-21.aif"
              length="805888"/>
      <sample loNote="22" hiNote="33" rootNote="33" path="DefaultPiano-33.aif"
              length="807552"/>
      <sample loNote="34" hiNote="45" rootNote="45" path="DefaultPiano-45.aif"
              length="759168"/>
      <sample loNote="46" hiNote="57" rootNote="57" path="DefaultPiano-57.aif"
              length="756480"/>
      <sample loNote="58" hiNote="69" rootNote="69" path="DefaultPiano-69.aif"
              length="758656"/>
      <sample loNote="70" hiNote="77" rootNote="77" path="DefaultPiano-77.aif"
              length="595328"/>
      <sample loNote="78" hiNote="89" rootNote="89" path="DefaultPiano-89.aif"
              length="457600"/>
      <sample loNote="90" hiNote="96" rootNote="96" path="DefaultPiano-96.aif"
              length="469888"/>
      <sample loNote="94" hiNote="108" rootNote="108" path="DefaultPiano-108.aif"
              length="75264"/>
    </group>
  </groups>
  <effects>
    <effect type="lowpass_4pl" frequency="22000.0"/>
    <effect type="reverb" wetLevel="0.4999999888241291"/>
  </effects>
</DecentSampler>