To make a new instrument set available to Box Of Stops, add the new <tt>.instrument-set</tt> file to the <tt>instrument-sets</tt> directory, and [[Restarting|restart]] Box Of Stops to pick this up.
== Creating a new instrument set ==
=== Find out the Midi details ===
To create a new instrument set you will need to be able to get hold of some Midi message values for the instruments on your keyboard or synth. These can normally be downloaded from the manufacturer, and will be found either in an appendix in the User Guide, or more commonly as a separate Midi Implementation or Midi Specification Guide.
The details you are looking for will look something like this:
{| class="wikitable"
! style="text-align:left;"| Name !! Bank MSB !! Bank LSB !! Program Change
|-
| Church Organ 1 || 0 || 66 || 19
|-
| Church Organ 2 || 8 || 69 || 19
|-
| Nason flute 8' || 16 || 66 || 19
|-
| Combo Jazz Organ || 0 || 70 || 18
|-
| Ballad Organ || 0 || 69 || 18
|}
This could be called a Voice List or a Tone List, depending on the manufacturer.
You will need:
* (Optionally) a list of categories the instruments are grouped into
* A list of instrument names
* Three Midi values for each instrument - '''Bank MSB''', '''Bank LSB''' and '''Program Change'''. Some older instruments will only have a Program Change value.
Note, with the Program Change (or PC) value, there are two standards, one using the Midi values 0 to 127, the other using 1 to 128. A Box Of Stops instrument set needs values from '''0''' to '''127'''. One way to spot which standard is being used is to look for some well known instruments in the list, e.g. a Grand Piano should be 0, and a Church Organ should be 19. If your guide shows these as 1 and 20, you'll need to subtract 1 from all the Program Change values.
=== Instrument set file overview ===
As mentioned above, instrument sets are stored in an <tt>.instrument-set</tt> file. This is a plain text file that can be edited in any text editor.
The format of the file is something called JSON, which designed to be able to be read by a computer, and be (relatively) editable by a human too. The structure is quite simple, if you are at all familiar with editing text files you are encouraged to have a go. But please pay a bit of attention to the structure - for instance that opening and closing brackets match, and that commas are in the right places.
If you prefer, there are editors available that are specifically designed to help with editing a JSON file. E.g. http://www.jsoneditoronline.org/ will let you edit the text from a <tt>.instrument-set</tt> file directly online, including indicating (roughly) where there are any errors in the file format, and showing you how it understands the data in the file.
=== Instrument set file detail ===
We strongly suggest you start from an example <tt>.instrument-set</tt> file. This will give you the outline to base your instrument set on. From there the task is mainly one of copying and pasting, and inserting your instrument details.
The next few sections below describe the meaning of each part of the file.
==== Version and name ====
The first two name/value pairs in the <tt>.instrument-set</tt> file are the version and name:
{
"version" : "0.0.1",
"name": "Roland HP201",
Please leave '''version''' as you found it in the example file. This is to ensure that future versions of Box Of Stops will be able to continue to read this file.
The '''name''' is how you will see the instrument set in Box Of Stops. Make sure to change this for your new instrument set.
==== Categories ====
The instruments should then be grouped by category. For example the following comes from the General Midi 1 instrument set that comes with Box Of Stops:
{
"version" : "0.0.1",
"name": "General Midi 1",
"categories": [
{
"name": "Organ",
"instruments": [
... omitted ...
]
},
{
"name": "Brass",
"instruments": [
... omitted ...
]
}
]
}
If it is a short list of instruments, a single category is fine.
==== Instruments ====
Then in each category, there is a list of instruments, each with the three Midi values described [[#Find out the Midi details|above]].
This is a short, but complete instrument set file, based around a single category "All":
{
"version" : "0.0.1",
"name": "Roland HP201",
"categories": [
{
"name": "All",
"instruments": [
{
"name": "Church Organ 1",
"bankMsb": "0",
"bankLsb": "66",
"program": "19"
},
{
"name": "Church Organ 2",
"bankMsb": "8",
"bankLsb": "69",
"program": "19"
},
{
"name": "Nason flute 8'",
"bankMsb": "16",
"bankLsb": "66",
"program": "19"
},
{
"name": "Combo Jazz Organ",
"bankMsb": "0",
"bankLsb": "70",
"program": "18"
},
{
"name": "Ballad Organ",
"bankMsb": "0",
"bankLsb": "69",
"program": "18"
}
]
}
]
}
''Page under construction ... to be continued''