DaTuner Custom Instruments

The capability to support custom instruments (and additional temperaments) has recently been added to DaTuner Pro.  A limited number of predefined instruments are supported in DaTuner Lite.  These instruments are accessed by long-pressing the screen and selecting “Choose Instrument

Custom Instruments File Format (XML)

Custom instruments are defined in a file format called .xml, which easy to read for a human (you!) and for DaTuner.

Xml files are simply files that allow tags and text to be intermingled, with the tags surrounding the text defining what the text means.  Since XML is a standard format (similar to HTML) there are many tools to allow editing of these files.

XML specifies only the formatting of the file; how the tags and text are combined.  It does not specify which tags are supported; that is up the application.

XML Hierarchy

In DaTuner’s hierarchical XML format, a file consisting of a single tuning looks like this:

<DaTuner>

  <Instrument name="My Guitar">

    <SubInstrument name="My 6 String">

      <Tuning name="My Drop D" ver="0.01">

        <NoteElement note="D2"></NoteElement>

        <NoteElement note="A2"></NoteElement>

        <NoteElement note="D3"></NoteElement>

        <NoteElement note="G3"></NoteElement>

        <NoteElement note="B3"></NoteElement>

        <NoteElement note="E4"></NoteElement>

      </Tuning>

      <Tuning name="My Standard Tuning" ver="0.01">

        <NoteElement note="E2"></NoteElement>

        <NoteElement note="A2"></NoteElement>

        <NoteElement note="D3"></NoteElement>

        <NoteElement note="G3"></NoteElement>

        <NoteElement note="B3"></NoteElement>

        <NoteElement note="E4"></NoteElement>

      </Tuning>

    </SubInstrument>

  </Instrument>

</DaTuner>

It is apparent from the example above that the main supported tags in DaTuner’s XML format are DaTuner, Instrument, SubInstrument, and NoteElement.  These are the basic things you need for each instrument.  You could create a .xml file in your /DaTuner or /Download directory and copy and paste what you see above to create another 6-string Drop-D Guitar tuning.

The DaTuner tag is necessary to allow DaTuner to know that it should ignore other .xml files that do not start out with the DaTuner tag.

Extra Tuning and NoteElement Properties

The Tuning and NoteElement tags have extra properties that can be used to customize a tuning.

Tuning Properties

Example

<Tuning name="Standard" ver="0.01" symbolfont="lcd" superscriptfont="sans_serif" subscriptfont="lcd”>

ver="0.01"

The ver tag specifies the version for a particular tuning.  If two tunings with exactly the same name are found under the same instrument and subinstrument, then the one with the highest version number will be used.

symbolfont, superscriptfont, subscriptfont

There are 3 elements per note that can be displayed on the screen.  The fonts for these elements can be specified within the tuning tag.

Figure 1: Symbol (A), superscript(B), and subscript (C) on DaTuner screen

There are 4 fonts currently supported.

symbolfont

The symbolfont tag specifies the font that will be used for the symbol.  See (A.) in figure 1.

superscriptfont

The symbolfont tag specifies the font that will be used for the symbol.  See (B.) in figure 1.

subscriptfont

The symbolfont tag specifies the font that will be used for the symbol.  See (C.) in figure 1.

transposition

The transposition tag specifies that a transposition of <transposition> will be applied to the tuning after all notes of the tuning are applied.  For instance transposition=”2” would shift the tuning by two semitones.

scale=

The scale tag specifies the start point of the scale.  This defaults to “C”, meaning that the octave shift is at every C.  If you want octave to shift at A or B, then specify “A” or “B” for this element.  For instance, if you specified scale=”B”, notes you specify would go …F2, F#2, G2, G#2, A2, A#2, B3, C3, D3

reference=

The reference tag specifies the reference frequency for the tuning.  The default reference frequency is 440Hz.  For example, to use a reference frequency of 442Hz, specify reference=”442” .

NoteElement Properties

Display Elements

There are 3 possible display elements on the screen at a time,

This example is for the Drop-D 6-string guitar tuning, which was used in the screenshot in Figure 1.

  <NoteElement note="D2" symbol="6" superscript="D2" subscript="73.4Hz" ></NoteElement>

  <NoteElement note="A2" symbol="5" superscript="A2" subscript="110.0Hz"></NoteElement>

  <NoteElement note="D3" symbol="4" superscript="D3" subscript="146.8Hz"></NoteElement>

  <NoteElement note="G3" symbol="3" superscript="G3" subscript="196.0Hz"></NoteElement>

  <NoteElement note="B3" symbol="2" superscript="B3" subscript="246.9Hz"></NoteElement>

  <NoteElement note="E4" symbol="1" superscript="E4" subscript="329.6Hz"></NoteElement>

note="A2"

Specifying note by note and octave

Individual notes can be specified by using the note[A..G] followed by a symbol for flat[#] or sharp[s] followed by the octave [ any number within range ].

<NoteElement note="E2"></NoteElement>

Specifying note by note only

A note or temperament that spans the entire chromatic scale in DaTuner can be specified by leaving out the octave.  The note will then be applied to all octaves.  A temperament for all octaves can look like this:

<Tuning name="Equal, Perfect Fourth" ver="0.01">

        <NoteElement note="A" cents="0"></NoteElement>

        <NoteElement note="A#" cents="-0.391"></NoteElement>

        <NoteElement note="B" cents="-0.782"></NoteElement>

        <NoteElement note="C" cents="3.519"></NoteElement>

        <NoteElement note="C#" cents="3.128"></NoteElement>

        <NoteElement note="D" cents="2.737"></NoteElement>

        <NoteElement note="D#" cents="2.346"></NoteElement>

        <NoteElement note="E" cents="1.955"></NoteElement>

        <NoteElement note="F" cents="1.564"></NoteElement>

        <NoteElement note="F#" cents="1.173"></NoteElement>

        <NoteElement note="G" cents="0.782"></NoteElement>

        <NoteElement note="G#" cents="0.391"></NoteElement>

      </Tuning>

cents="-0.391"

An offset in the note mapping, used for temperaments, can be specified by using the cents property.  This will take the “ideal” chromatic frequency for the note and then adjust it by the number of cents in the cents tag.

        <NoteElement note="C#2" cents="3.128"></NoteElement>

Specifying note by frequency

frequency=

The frequency property allows note elements to be specified to fixed frequencies, rather than to notes in the chromatic scale.  Here is an example for common test frequencies.

        <NoteElement frequency="125" symbol="125" superscript="Hz"></NoteElement>

        <NoteElement frequency="250" symbol="250" superscript="Hz"></NoteElement>

        <NoteElement frequency="500" symbol="500" superscript="Hz"></NoteElement>

        <NoteElement frequency="1000" symbol="1" superscript="kHz"></NoteElement>

        <NoteElement frequency="2000" symbol="2" superscript="kHz"></NoteElement>

        <NoteElement frequency="4000" symbol="4" superscript="kHz"></NoteElement>

        <NoteElement frequency="8000" symbol="8" superscript="kHz"></NoteElement>


DaTuner Startup

DaTuner does the following on startup:

  1. Load standard chromatic mapping
  2. Load any selected temperament from /DaTuner/datuner_temperaments.csv, which is the original method of applying temperaments.
  3. Load all instruments from /DaTuner/datuner_default_instruments.xml, then any .xml files in /DaTuner, then any .xml files in  /Download.  (If you want your own instruments included, you can put them in your own .xml file in one of these directories.)
  4. Load the selected instrument mapping over the selected temperament.  Any “chromatic” tunings specified only by note, like E2, A4, will land where the temperament placed them.  However, if they are specified by frequency, they will not be shifted.

This means that you can apply an instrument mapping over a temperament (from datuner_temperaments.csv), which will shift the notes in the instrument mapping by the cents offset specified in the temperament.

Creating/Sharing Custom Instruments

Since DaTuner can load instruments from the /DaTuner directory, or from your device's /Download directory.

There are several ways to get these custom instruments files:

1.) Create them yourself using any text editor.

2.) Download them from somewhere on the internet.

3.) Send me an email with the instrument and tuning you desire and wait until we have time to implement it and release a DaTuner.

Create them yourself using any text editor

You can add the tunings to DaTuner yourself.  Give it a file name ending in .xml, and start with the template at the beginning of this document.  Finally, download it or place it in /DaTuner or in /Downloads and restart DaTuner.  If it doesn’t show up, ensure your tuning names are unique or your version numbers “ver=” are higher than the versions in the template files.

Download them from somewhere on the internet

With time, the “cloud” will create tunings for all possible instruments.  Downloading them from the internet with your phone will place them in /Download, which DaTuner will automatically search for new tunings.

Send me an email with the instrument and tuning you desire and wait until we have time to implement it and release a DaTuner.

This is by far the slowest method.  As DaTuner is a part time project and I have been extremely busy the last couple of years, you may have to patient.  This will hopefully ease up in the future.