Manual Layout Mappings

All the material in this section is demonstrated in the video linked below.

In this section, I will introduce the concept of manual layouts. The next section on the layout engine includes a more technical and rigorous description and tells you how to create your own layouts.

The built-in keyboard configuration includes one manual layout called "JI" and one hybrid layout that includes an isomorphic layout and manual layout occupying different regions of the keyboard. The accompanying video includes demonstrations of everything I describe here.

Before we dive in, I need to improve the precision of the terms I've been using. The Syntoniq keyboard defines the concept of a layout which consists of a number of mappings. A mapping is the thing that maps notes to keys. Throughout the manual, I have been treating layouts like they contain a single mapping and thus using the terms interchangeably. It's time to stop doing that. When I refer to layout, I'm referring to the entire collection of keys on the screen. When I refer to mapping, I'm talking about the exact way in which the layout is defined. For a lot of this section, they are the same, but you can create hybrid layouts with multiple mappings, and then it matters.

Below, you will see a view of the web UI for the JI layout. Here is the HexBoard:

p↑3
405/256

F↑3
81/80

EK↑3
297/256

e'↑3
27/20

Bh↑3
189/128

p↑3→
405/256

F↑3→
81/80

EK↑3→
297/256

e'↑3→
27/20

C↑3←
81/64

A↑3
27/16

I↑3
243/128

E↑3
135/128

D↑3
9/8

C↑3
81/64

A↑3→
27/16

I↑3→
243/128

E↑3→
135/128

D↑3→
9/8

p↑2
135/128

F↑2
27/20

EK↑2
99/64

e'↑2
9/5

Bh↑2
63/32

p↑2→
135/128

F↑2→
27/20

EK↑2→
99/64

e'↑2→
9/5

C↑2←
27/16

A↑2
9/8

I↑2
81/64

E↑2
45/32

D↑2
3/2

C↑2
27/16

A↑2→
9/8

I↑2→
81/64

E↑2→
45/32

D↑2→
3/2

p↑
45/32

F↑
9/5

EK↑
33/32

e'↑
6/5

Bh↑
21/16

p↑→
45/32

F↑→
9/5

EK↑→
33/32

e'↑→
6/5

C↑←
9/8

A↑
3/2

I↑
27/16

E↑
15/8

D↑
1

C↑
9/8

A↑→
3/2

I↑→
27/16

E↑→
15/8

D↑→
1

p
15/8

F
6/5

EK
11/8

e'
8/5

Bh
7/4

p→
15/8

F→
6/5

EK→
11/8

e'→
8/5

C←
3/2

A
1

I
9/8

E
5/4

D
4/3

C
3/2

A→
1

I→
9/8

E→
5/4

D→
4/3

p↓
5/4

F↓
8/5

EK↓
11/6

e'↓
16/15

Bh↓
7/6

p↓→
5/4

F↓→
8/5

EK↓→
11/6

e'↓→
16/15

C↓←
1

A↓
4/3

I↓
3/2

E↓
5/3

D↓
16/9

C↓
1

A↓→
4/3

I↓→
3/2

E↓→
5/3

D↓→
16/9

p↓2
5/3

F↓2
16/15

EK↓2
11/9

e'↓2
64/45

Bh↓2
14/9

p↓2→
5/3

F↓2→
16/15

EK↓2→
11/9

e'↓2→
64/45

C↓2←
4/3

A↓2
16/9

I↓2
1

E↓2
10/9

D↓2
32/27

C↓2
4/3

A↓2→
16/9

I↓2→
1

E↓2→
10/9

D↓2→
32/27

p↓3
10/9

F↓3
64/45

EK↓3
44/27

e'↓3
256/135

Bh↓3
28/27

p↓3→
10/9

F↓3→
64/45

EK↓3→
44/27

e'↓3→
256/135

C↓3←
16/9

A↓3
32/27

I↓3
4/3

E↓3
40/27

D↓3
128/81

C↓3
16/9

A↓3→
32/27

I↓3→
4/3

E↓3→
40/27

D↓3→
128/81

Here is the Launchpad:

Shift				Transpose	Sustain
▲	Bh↑2← 63/32	p↑2 135/128	F↑2 27/20	EK↑2 99/64	e'↑2 9/5	Bh↑2 63/32	p↑2→ 135/128	F↑2→ 27/20
▼	C↑2← 27/16	A↑2 9/8	I↑2 81/64	E↑2 45/32	D↑2 3/2	C↑2 27/16	A↑2→ 9/8	I↑2→ 81/64
Reset	Bh↑← 21/16	p↑ 45/32	F↑ 9/5	EK↑ 33/32	e'↑ 6/5	Bh↑ 21/16	p↑→ 45/32	F↑→ 9/5
	C↑← 9/8	A↑ 3/2	I↑ 27/16	E↑ 15/8	D↑ 1	C↑ 9/8	A↑→ 3/2	I↑→ 27/16
	Bh← 7/4	p 15/8	F 6/5	EK 11/8	e' 8/5	Bh 7/4	p→ 15/8	F→ 6/5
	C← 3/2	A 1	I 9/8	E 5/4	D 4/3	C 3/2	A→ 1	I→ 9/8
	Bh↓← 7/6	p↓ 5/4	F↓ 8/5	EK↓ 11/6	e'↓ 16/15	Bh↓ 7/6	p↓→ 5/4	F↓→ 8/5
Show Notes	C↓← 1	A↓ 4/3	I↓ 3/2	E↓ 5/3	D↓ 16/9	C↓ 1	A↓→ 4/3	I↓→ 3/2	Scroll layouts
	1	2	3	4	5	6	7	8

There is a lot of new stuff here, so let's explain. As I explain, you can find what I'm talking about in both diagrams.

The first thing to know is that this layout uses Syntoniq's generated note names. These are not your familiar diatonic note names. Please review Using Generated Scales. With generated scales note A (also a, A0, and a0) is the tonic of the scale. On the HexBoard, you can find the yellow note with A on its top row and 1 on its bottom row by counting up to the seventh row from the bottom and the second column from the left. On the Launchpad, it is row 3, column 2. This particular manual mapping is defined to be two rows high and five rows wide. I will reveal the actual definition in layout engine section. For now, here's what you need to know:

• The top row is p F EK e' Bh
• The bottom row is A I E D C
• The anchor note is the A at the lower-left.
• The horizontal tile factor is 2.
• The vertical tile factor is 3/2.

As you examine the diagrams, you can see this pattern of notes as stated along with their ratios, computed using the generated note syntax. For example, the note Bh has the ratio of 7/6, and the note e' is 8/5. In this case, the apostrophe indicating the octave mark appears explicitly in the mapping's definition. It is not inferred by Syntoniq. In general, it is not possible to map a tiled note to cycle marks.

The next thing to notice is the arrows. This layout includes the characters ←, →, ↑, and ↓, sometimes followed by a number. These indicate the number of horizontal or vertical tilings of the mapping. For example, if you look 5 keys to the right of the A key, you will find a note labeled A→. Its ratio is also shown as 1. If you play these notes one after the other, you will see the following in the keyboard's console output:

Note: A (base × 1 = 264), scale=JI, base=264
Note: A→ (base × 1 × 2 = 528), scale=JI, base=264

Observe:

• In the web UI, the ratio of both notes is 1. This is because, as with isomorphic mappings, the web UI always shows relative pitches normalized to within the scale's cycle, which in this case is an octave. With manual mappings, relative pitches are relative to the pitch of the untiled anchor.
• The note names with the tiling arrows are displayed.
• The pitch has an extra factor for A→ and is shown as (base × 1 × 2 = 528) indicating that the pitch, 528, is the result of multiplying the base frequency (shown as 264) first by 1 (the base-relative pitch) and then by 2, which is the tile factor.

Let's go two rows above that. That note is labeled A↑→, and on the keyboard its relative pitch shows 3/2, and the color is blue, our color for fifths. If you play it, you can hear that it is, in fact, an octave and a fifth (which, normalized to the octave, has ratio 3/2) above the tonic. You will also notice that its note name includes A, not C, which would be 3/2. Why is that? In this case, it happens that A↑→ lands on a pitch corresponding to a note in the scale, but this doesn't always happen. If you look just one character to the right, you will find the note I↑→ with the ratio 27/16. While you can spell that note as a generated note (one way is CI), the note CI doesn't appear in the mapping. If our tile factor were something like ^1|12, then the tiled note wouldn't land in the JI scale at all (though it could still be written as a generated note).

Quick aside: while it would have been possible to design this so that we always presented a generated note, there are two big reasons not to do this. The main one is that manual mappings don't have to use generated notes at all! The second one is that, even if we said we'd only do this with generated scales, note names would get very long and complex, and there are an infinite number of ways of writing any note, so we'd have to pick some way to do it, and it wouldn't necessarily reflect the harmonic intent! Make sense? If not, no worries...you just accept that there are good reasons we don't try to generate notes outside the mapping!

When we play the note A↑→, we see the following output:

Note: A↑→ (base × 1 × 3 = 792), scale=JI, base=264

Here we have a tile factor of 3, which comes from one horizontal tiling (factor 2) and one vertical tiling (factor 3/2) since $2 \times \frac{3}{2} = 3$. If you play I↑→, you see this:

Note: I↑→ (base × 9/8 × 3 = 891), scale=JI, base=264

This is showing us that the frequency of 891 Hz comes from the base (264) multiplied by 9/8 (the base-relative pitch) multiplied by 3 (the tile factor). If we had transposition in play, that would also show up here.

This seems complicated, but there are reasons it's done the way it is (and I can assure you, a great deal of thought and iteration went into it!).

• The web UI is about finding the note. When you've defined a manual mapping, you want to see note names that match what you defined, and as explained, there often is no note name that matches the right base-relative pitch.
• The tile factors might not be related to the scale. They might even include 1 to indicate a simple wrap-around. The only way to clearly show tiling is to introduce a new symbol.
• The console output is about knowing the details of the pitch. Tile factor is a different thing from either cycles (octaves, etc.) or transposition. It needs to be shown its own way.

For all these reasons, we've introduced this additional notation. While dense, once you get used to it, it really does pack in the information you need.

I'll wrap up this section by showing you a few more layouts. Here's one that contains more than one mapping. The layout entitled "JI-19-EDO" is shown below. For HexBoard:

e#
^7|19

g%
^10|19

a%
^13|19

b%
^16|19

c'
1

d'
^3|19

e'
^6|19

f#'
^9|19

g#'
^12|19

d%
^2|19

e%
^5|19

f
^8|19

g
^11|19

a
^14|19

b
^17|19

c#'
^1|19

d#'
^4|19

e#'
^7|19

g%'
^10|19

c
1

d
^3|19

e
^6|19

f#
^9|19

g#
^12|19

a#
^15|19

b#
^18|19

d%'
^2|19

e%'
^5|19

a,
^14|19

b,
^17|19

c#
^1|19

d#
^4|19

e#
^7|19

g%
^10|19

a%
^13|19

b%
^16|19

c'
1

d'
^3|19

g#,
^12|19

a#,
^15|19

b#,
^18|19

d%
^2|19

e%
^5|19

f
^8|19

g
^11|19

a
^14|19

b
^17|19

e#,
^7|19

g%,
^10|19

a%,
^13|19

b%,
^16|19

c
1

d
^3|19

e
^6|19

f#
^9|19

g#
^12|19

a#
^15|19

e%,
^5|19

f,
^8|19

g,
^11|19

a,
^14|19

b,
^17|19

c#
^1|19

d#
^4|19

e#
^7|19

g%
^10|19

c,
1

d,
^3|19

e,
^6|19

f#,
^9|19

g#,
^12|19

a#,
^15|19

b#,
^18|19

d%
^2|19

e%
^5|19

f
^8|19

b,2
^17|19

c#,
^1|19

d#,
^4|19

e#,
^7|19

g%,
^10|19

a%,
^13|19

b%,
^16|19

c
1

d
^3|19

g#,2
^12|19

a#,2
^15|19

b#,2
^18|19

d%,
^2|19

e%,
^5|19

f,
^8|19

g,
^11|19

a,
^14|19

b,
^17|19

c#
^1|19

p↑
45/32

F↑
9/5

EK↑
33/32

e'↑
6/5

Bh↑
21/16

p↑→
45/32

F↑→
9/5

EK↑→
33/32

e'↑→
6/5

C↑←
9/8

A↑
3/2

I↑
27/16

E↑
15/8

D↑
1

C↑
9/8

A↑→
3/2

I↑→
27/16

E↑→
15/8

D↑→
1

p
15/8

F
6/5

EK
11/8

e'
8/5

Bh
7/4

p→
15/8

F→
6/5

EK→
11/8

e'→
8/5

C←
3/2

A
1

I
9/8

E
5/4

D
4/3

C
3/2

A→
1

I→
9/8

E→
5/4

D→
4/3

For Launchpad:

Shift				Transpose	Sustain
▲	b, ^17|19	c# ^1|19	d# ^4|19	e# ^7|19	g% ^10|19	a% ^13|19	b% ^16|19	c' 1
▼	a#, ^15|19	b#, ^18|19	d% ^2|19	e% ^5|19	f ^8|19	g ^11|19	a ^14|19	b ^17|19
Reset	a%, ^13|19	b%, ^16|19	c 1	d ^3|19	e ^6|19	f# ^9|19	g# ^12|19	a# ^15|19
	g, ^11|19	a, ^14|19	b, ^17|19	c# ^1|19	d# ^4|19	e# ^7|19	g% ^10|19	a% ^13|19
	p↑ 45/32	F↑ 9/5	EK↑ 33/32	e'↑ 6/5	Bh↑ 21/16	p↑→ 45/32	F↑→ 9/5	EK↑→ 33/32
	A↑ 3/2	I↑ 27/16	E↑ 15/8	D↑ 1	C↑ 9/8	A↑→ 3/2	I↑→ 27/16	E↑→ 15/8
	p 15/8	F 6/5	EK 11/8	e' 8/5	Bh 7/4	p→ 15/8	F→ 6/5	EK→ 11/8
Show Notes	A 1	I 9/8	E 5/4	D 4/3	C 3/2	A→ 1	I→ 9/8	E→ 5/4	Scroll layouts
	1	2	3	4	5	6	7	8

In these mappings, notice that the bottom four rows have generated names using the same mapping as our "JI" layout, and the rows above that contain notes from 19-EDO.

Here's one that uses a completely custom scale that defines 64 notes: one for each of the first 64 steps of the harmonic sequence. The notes are named h1 through h64. On the HexBoard, it leaves part of the layout unmapped. Here it is for HexBoard:

h57
57/32

h58
29/16

h59
59/32

h60
15/8

h61
61/32

h62
31/16

h63
63/32

h64
1

h49
49/32

h50
25/16

h51
51/32

h52
13/8

h53
53/32

h54
27/16

h55
55/32

h56
7/4

h41
41/32

h42
21/16

h43
43/32

h44
11/8

h45
45/32

h46
23/16

h47
47/32

h48
3/2

h33
33/32

h34
17/16

h35
35/32

h36
9/8

h37
37/32

h38
19/16

h39
39/32

h40
5/4

h25
25/16

h26
13/8

h27
27/16

h28
7/4

h29
29/16

h30
15/8

h31
31/16

h32
1

h17
17/16

h18
9/8

h19
19/16

h20
5/4

h21
21/16

h22
11/8

h23
23/16

h24
3/2

h9
9/8

h10
5/4

h11
11/8

h12
3/2

h13
13/8

h14
7/4

h15
15/8

h16
1

h1
1

h2
1

h3
3/2

h4
1

h5
5/4

h6
3/2

h7
7/4

h8
1

And here it is for Launchpad:

Shift				Transpose	Sustain
▲	h57 57/32	h58 29/16	h59 59/32	h60 15/8	h61 61/32	h62 31/16	h63 63/32	h64 1
▼	h49 49/32	h50 25/16	h51 51/32	h52 13/8	h53 53/32	h54 27/16	h55 55/32	h56 7/4
Reset	h41 41/32	h42 21/16	h43 43/32	h44 11/8	h45 45/32	h46 23/16	h47 47/32	h48 3/2
	h33 33/32	h34 17/16	h35 35/32	h36 9/8	h37 37/32	h38 19/16	h39 39/32	h40 5/4
	h25 25/16	h26 13/8	h27 27/16	h28 7/4	h29 29/16	h30 15/8	h31 31/16	h32 1
	h17 17/16	h18 9/8	h19 19/16	h20 5/4	h21 21/16	h22 11/8	h23 23/16	h24 3/2
	h9 9/8	h10 5/4	h11 11/8	h12 3/2	h13 13/8	h14 7/4	h15 15/8	h16 1
Show Notes	h1 1	h2 1	h3 3/2	h4 1	h5 5/4	h6 3/2	h7 7/4	h8 1	Scroll layouts
	9

The accompanying video will demonstrate both of those layouts.

The shift and transpose features work as you'd expect since tiling of manual mappings still creates an infinite space where you can always know what note should be on a key. The accompanying video demonstrates this as well, including showing how it works with the hybrid layout. In the next section, we'll unveil the full complexity and power of the layout engine and show you how to create your own custom mappings and to create layouts containing multiple mappings.