MusicTool data structures : documentation

I.1: Bitwise Representation of MusicTool external types :

NB: external types are the types that users can interract with while using the MusicTool interpreter or an smtool command

• S_SCALE:
size: 2bytes; relevant bits: 11 first bits.
1-hot representation of a scale where presence of the fundamental is assumed.
• S_DODEC :
size: 8 bytes; relevant bits: 48 first bits.
compacted array of number between 1 and 12. each number is stored on 4bits w the first being stored from lsb to bit 4.
• S_INTERVAL_STRUCTURE :
size: 8 bytes ; relevant bits: min 4 bits;
max 4*12 bits compacted array of number between 1 and 12. each number is stored on 4bits w the first being stored from lsb to bit 4.
• S_INTERVAL_VECTOR
size: 4 bytes ; relevant bits: 24 first bits ;
compacted array of 6 numbers between 1 and 12. each number stored on 4 bits

I.2: Bitwise Representation of MusicTool internal types :

NB: external types are the types used inside MusicTool as intermediate representation or the constituant of the external types.

These are the internal types that are contained inside external types:

• TRIADS_BITS:
size: 1 byte; relevant bits: lsb to 4 ; in the triad format, used to represent the triad. minor triad is 1 , major 2, dim 3, aug 4, sus2 5 , sus4 6
• DEGREES_BITS :
size: 1 byte; relevant bits : lsb to 4 ; in the different chords formats, uses number from 0 to 11 to represent a degree. DEG_I is 0, DEG_bII is 1,...,DEG_VII is 11
• TRIAD:
size: 1 byte; relevant bits: all of them. Internal representation of a triad in a triad prog. lsb to bit 3 stores the degree in DEGREE_BITS format ; bit 4 to msb store the triad in the TRIAD_BIT format
• CHORD :
size: 2 bytes; relevant bits: all of them. Internal representation of a chord in a chprog. lsb to bit 3 stores the degree in DEGREE_BITS format. ; bit 4 to msb (bit 15) store the chord in the PITCH_CLASS_SET/S_EXTENSIONS format
• PITCH_CLASS_SET:
size: 2 bytes; relevant bits : lsb to 11. Represents a set of notes in a 1-HOT format. Presence of the note {0} is wether lsb is set presence of {1} is wether second bit set ,...
1-hot representation of a pitch class set. Very similar to scale except each degree is stored on a bit which means that lsb is wether 0 is in the PCS so on. bit 13 is an error flag.
• BOOKENTRY:
size: 8 bytes: relevant bits: all 64 bits.;
first 12 bits store the S_SCALE of the prog. ; then the next 52 bits contain the prog itself. The PCS is stored in a 1-hot format. The prog is a compacted array. Each number is stored on 4 bits; it's length thus goes from 1 to 13.
• INTERVAL_STRUCTURE :
size : 8 bytes ; relevant bits: lsb to 48.
the interval structure is divided into 4 bits sections containing numbers from 1 to 11 .
from bit 48 onward bits are flags.
special case : a scale containing only 1 note is translated into an empty interval structure which is printed as [12]
interval structures can't be saved but are the result of a call to "scale intv struct"
example: S_INTERVAL_STRUCTURE of { 0 2 4 5 7 9 11} (maj scale) (40x0) 0001 0010 0010 0001 0010 0010
• INTERVAL_VECTOR:
size: 4 bytes ; relevant bits: lsb to bit 24.
the interval vecotr is divided in 6 4bits sections containing numbers from 0 to 12.
if u take the intv vector < 2, 5, 4, 3, 6, 1> (intv vector of the major scale)
ur bitwise rep would be: 0001 0110 0011 0100 0101 0010 (or 0x163452)
the edge cases are the intv vect of the chromatic scale : <12 , 12, 12, 12 ,12,6>
its rep is : 0110 1100 1100 1100 1100 1100 (0x6CCCCC)
and the unisson scale : <0 ,0 ,0,0,0,0>
its rep is: 0000 0000 0000 0000 0000 0000

These are the internal types that are only used as intermediate representation :

• S_EXTENSIONS :
other name for S_SCALE size: 2 bytes; relevant bits : lsb to 11. Represents a set of notes in a 1-HOT format. Presence of the note {0} is assumed, presence of {1} is wether lsb is set ,...
1-hot representation of a pitch class set. Very similar to scale except each degree is stored on a bit which means that lsb is wether 0 is in the PCS so on. bit 13 is an error flag.
• TRIADS_IN_SCALE :
size: 1 byte ; relevant bits: lsb to bit 6. 1-HOT representation of triads present in a given scale. lsb is set if minor triad is present; second bit is set if major triad,
• WORD_BITS :
size : 1 byte ; used to tokenize I,V,b,sus2,m,+,- when syntaxchecking chord / triad progs.

II.1: the "SAVED_" objects:

MusicTool uses singly linked lists to save objects in an environments. These objects can be scales, chord progs, harmonised scale, Pitch class sets or triad progressions. They are thus called S_SAVED_SCALES S_SAVED_MODES, S_SAVED_PROG, S_SAVED_DODEC, S_SAVED_TRIAD.

II.2: S_MODES:

S_MODES is simply an array of S_SCALES. It is not wrapped inside a structure where the length of it is stored because it's length is ALWAYS the length of the scale it contains.

II.3: S_TRIAD_PROG / S_CHPROG:

S_TRIAD_PROG is a simple structure containing an array of TRIADS and the length of the array. S_CHPROG is the same thing except it CHORD elements in it's array.

III.1: S_USERINFO:

S_USERINFO is a structure containing a reference to one of each S_SAVED_... structure in MusicTool as well as the number of elements in each of these structures.
At start, MusicTool initialises an S_USERINFO structure to store elements saved during the session. when a "save" function is called.

III.2: the prog book :

NB: THE PROG BOOK' CURRENT IMPLEMENTATION IS AWFUL. IT SHOULD BE
A TABLE WHERE INDEXES CORRESPOND TO THE LENGTH OF THE ENTRIES AT EACH INDEX (progs of length 1 stored at index 0, 2 index 1...)
AT EACH INDEX, PROGS WOULD BE STORED IN SMALLER TABLES WHERE THE KEYS WOULD BE THE PITCH_CLASS_SET ASSOCIATED WITH THE PROG
The prog book is a dynamic array used to stored BOOKENTRY elements. It is initialised with 30 slots when MusicTool is launched and can be edited by reading an environment containing an env book() section or by using the command "book add"