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]```
6 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.

Hi all,

I donā€™t really get the purpose/use case of
CC_NUMBER:DEFAULT=xx NAME

Would it duplicate the default cc to that Nb ?
hence:
102:DEFAULT=07 MySwankyVolumeName

PS: I donā€™t own yet an Hapax to test and couldnā€™t find an example in the definitions repo.

I also see insconsistency (typo) in the doc for ASSIGN:

For PB and AT, any text after the TYPE will be ignored

ā€¦
#### For PB: DEFAULT_VALUE must be a valid number between 0 and 16383
ā€¦,

Please note default value will be ignored for PB and AT messages.

Seems lik ā€œ#### For PB: DEFAULT_VALUE must be a valid number between 0 and 16383ā€ should be removed.