Custom Instruments

Custom Instruments are now finally supported in DaTuner Pro!

Here are some instrument files, which can simply be downloaded and unzipped to your device’s Download/ or Downloads/ folder and will be automagically loaded by DaTuner Pro.

DaTuner, on startup, will enter each of the subdirectories in DaTuner/, Download/, and Downloads/ looking for *.xml files, and if they have the format described in this document, then the tuning file will be loaded.

Guitar – James Taylor for DaTuner courtesy of Leigh James at lordjamesmusic.com

If you want Buzz Feiten tuning using Android on your six-string guitar, please let me know if this custom instrument works for you, following the guidelines here.

Guitar – Buzz Feiten for DaTuner

Nyckelharpa for DaTuner

Link to this help file as a web page

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:

example_6_string

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.

image00

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

There are 4 fonts currently supported.

  • sans_serif
  • serif
  • monospace
  • lcd

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, specifyreference=”442” .

NoteElement Properties

Display Elements

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

  • Symbol (Figure 1, A)
  • Superscript (Figure 1, B)
  • Subscript(Figure 1, C)

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

example_with_extra_symbols

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.

2 thoughts on “Custom Instruments

Leave a Reply