Instrument Definition Template

Wonder if this could be pinned to the top of this sub-forum.

Here is the blank Instrument Definition file for Hapax.

VERSION 1 # Currently, this should only be 1.

# Supports all alphanumeric ASCII, and ' ', '_', '-', '+' - can also be NULL
TRACKNAME NULL

# Can be POLY, DRUM, MPE, or NULL
TYPE NULL

# Can be A, B, C, D, USBD, USBH, CVGx (x between 1&4), CVx, Gx, or NULL
OUTPORT NULL

# Can be x (between 1-16), or NULL -- this is ignored if output port is not MIDI
OUTCHAN NULL

# Can be NONE, ALLACTIVE, A, B, USBH, USBD, CVG, or NULL
INPORT NULL

# Can be x (between 1-16), ALL, or NULL. This definition will be ignored if INPORT is NONE, ALLACTIVE or CVG
INCHAN NULL

# This defines the default 'MAX RATE' for automation lanes.
# Can be NULL, 192, 96, 64, 48, 32, 24, 16, 12, 8, 6, 4, 3, 2, 1
MAXRATE NULL

# DRUMLANES
# Syntax: ROW:TRIG:CHAN:NOTENUMBER NAME
# ROW must be between 1 and 8
# TRIG can be between 0 and 127, or NULL
# CHAN can be a number between 1 and 16, Gx, CVx, CVGx (x between 1 and 4), or NULL
# NOTENUMBER can be between 0 and 127, or NULL
# NAME supports all alphanumeric ASCII, and ' ', '_', '-', '+' - can also be NULL
# Please note this section will be discarded for tracks which are not DRUM tracks
[DRUMLANES]
[/DRUMLANES]


# PC
# Syntax: NUMBER NAME
# number must be either:
#   - A number (for simple PC)
#   - Three numbers, delimited by ':', which represent PC:MSB:LSB. You can put 'NULL' to not set the MSB/LSB.
# PC must be between 1...128
# MSB/LSB must be between 0...127
[PC]
[/PC]


# CC
# Syntax: CC_NUMBER NAME or CC_NUMBER:DEFAULT=xx NAME
# DEFAULT_VALUE must be a valid number between 0 and 127
[CC]
[/CC]


# NRPN
# Syntax: "MSB:LSB:DEPTH NAME" or "MSB:LSB:DEPTH:DEFAULT=xx NAME"
# Lsb & msb should be between 0 and 127
  # Note: LSB can be over 127 ONLY if MSB is 0 or omitted
  # e.g. '0:1026:7 FOO', or ':2000:7 BAR' 
  # the examples above would be equivalent to '8:2:7 FOO' and '15:80:7 BAR' respectively
# DEPTH can be 7 or 14
# For NRPN: DEFAULT_VALUE must be a valid number, either between 0 and 127 (for 7 bit NRPNs) or between 0 and 16383 (for 14bit NRPNs)
[NRPN]
[/NRPN]


# ASSIGN
# Syntax: POT_NUMBER TYPE:VALUE or POT_NUMBER TYPE:VALUE DEFAULT=DEFAULT_VALUE
# POT_NUMBER must be between 1 and 8
# TYPE can be "CC", "PB" (pitchbend), "AT" (aftertouch), "CV", "NRPN", or "NULL" (this won't assign the pot).
# Non explicitly-defined pots will be considered "NULL"
# VALUE VALIDATION
#### For CC: Value must be a valid number between 0 and 119
#### For PB and AT, any text after the TYPE will be ignored
#### For CV, value must be between 1 and 4
#### For NRPN, value must be MSB:LSB:DEPTH, with both lsb & msb bebtween 0 and 127, and DEPTH being either 7 or 14
# DEFAULT VALUE
#### For CC: DEFAULT_VALUE must be a valid number between 0 and 127
#### For PB: DEFAULT_VALUE must be a valid number between 0 and 16383
#### For NRPN: DEFAULT_VALUE must be a valid number, either between 0 and 127 (for 7 bit NRPNs) or between 0 and 16383 (for 14bit NRPNs)
#### For CV: DEFAULT_VALUE must be either a valid number between 0 and 65535, or a voltage between -5V and 5V, e.g. "-4.25V" or "1.7V"
#### Please note default value will be ignored for PB and AT messages.
[ASSIGN]
[/ASSIGN]


# AUTOMATION
# Syntax: TYPE:VALUE
# TYPE can be "CC", "PB" (pitchbend), "AT" (aftertouch), "CV", or "NRPN"
# VALUE VALIDATION
#### For CC: Value must be a valid number between 0 and 119
#### For PB and AT, any text after the TYPE will be ignored
#### For CV, value must be between 1 and 4
#### For NRPN, value must be MSB:LSB:DEPTH, with both lsb & msb bebtween 0 and 127, and DEPTH being either 7 or 14
# NOTE: You are limited to 64 automation lanes
[AUTOMATION]
[/AUTOMATION]


# This section will be readable from Hapax.
[COMMENT]
[/COMMENT]```
5 Likes

A good resource for midi CC info for many pieces of hardware can be found at this link : https://midi.guide/. This will help you create definition files a little more quickly, if they don’t already exist on the forum

1 Like

The definition file template linked from the manual is missing this section which was added in a later firmware update.

# Syntax: CC_MSB:CC_LSB NAME or CC_MSB:CC_LSB:DEFAULT=xx NAME
# DEFAULT_VALUE must be a valid number between 0 and 16383
[CC_PAIR]
[/CC_PAIR]
2 Likes

yeah, I personally, don’t think we should have another copy here on the forum, as well as the official template…

duplication tends to lead to issues where ‘copies’ become out of date, unless they are maintained (which doesnt happen).
however, I could create a topic that links to the one in the manual, and perhaps ‘flesh out’ the topic, with some other useful info… as I can see that the natural place to look for info about Instrument Defs is this category.

for completeness here is a link to official template

thanks @polynil useful to know.
if you notice the ‘official template’ is incomplete, it would be useful to notify squarp via the contact form (if you haven’t already) … its easy for devs to overlook these things in the heat of new firmware releases :slight_smile:

@Thibault_Squarp ,
perhaps you could add the extra bit that @polynil has quoted? and verify the official copy is up to date?

also in the manual, Instrument Definitions are ‘hidden’ a bit under the “Track” part of the manual.
perhaps this could be move up a level, to make a little more prominent ?
( e.g whilst, I knew this information was in the manual , but I had to 'hunt around to find it ’ :wink: )

or perhaps make it a PDF, and included on the “getting started” front page, and have a link at the top?

anyway just a thought.

3 Likes

The “version number should always be 1” thing is a little weird when we have different versions now.

Will the real version 1 please stand up? :wink:

2 Likes

I’ve always thought that too! :laughing:

2 Likes

tl;dr; I suspect this is for functional comparison, rather than just ‘documentation’.

its likely considered a protocol/format version.

so it would only have to change if the format of the file was changed such that it would be incompatible with previous versions.

lets take the above cc_pair tag above…

if this is an optional tag, so
a) you do not have to include it for new firmware
b) previous versions of the firmware would ignore if it is present

then in this case this version has indeed not changed.

however, if the file would be incompatible with older firmware, or new firmware would require/prefer new version… then the would necessitate an increase in version number.

basically the idea is, when the version number is increased (e.g. to 2), then older/newer firmware would complain that you need to convert the to the appropriate format to use.

of course, we could discuss the merits of minor versions (eg 1.1)
but frankly, whilst they are used a lot in software, they are not the useful to end-user applications like this (imho) … as they dont yield functional changed (see point above), so a nice to have , rather than necessary.