@libraz/libcantus-wasm 0.0.0-stage → 1.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,64 @@
1
+ import { i as ChordToneRole, c as ChordLike } from './coerce-Cr9AZsTY.js';
2
+
3
+ /**
4
+ * Harmonic role a pitch plays within a chord.
5
+ *
6
+ * @category Functional Harmony
7
+ */
8
+ type HarmonyRole = ChordToneRole | 'tension' | 'doubling';
9
+ /**
10
+ * How firmly a pitch is locked to the chord's identity.
11
+ *
12
+ * - `identity`: moving it produces a different chord (the root).
13
+ * - `quality`: moving it flips the chord quality (the third).
14
+ * - `voicing`: it can move freely without changing chord identity or quality.
15
+ *
16
+ * @category Functional Harmony
17
+ */
18
+ type LockLevel = 'identity' | 'quality' | 'voicing';
19
+ /**
20
+ * A pitch's role, lock level, and owning chord.
21
+ *
22
+ * @category Functional Harmony
23
+ */
24
+ type VoicedRole = {
25
+ role: HarmonyRole;
26
+ lock: LockLevel;
27
+ belongsToChordId: number;
28
+ };
29
+ /**
30
+ * Classify a pitch's harmonic role and lock level within a chord.
31
+ *
32
+ * The role comes from the pitch's interval class above the chord root, read
33
+ * against the chord's own template: root (0), third (3/4), fifth (6/7/8),
34
+ * sixth or seventh (9/10/11). Every pitch the template does not claim is
35
+ * `'tension'` — including one that is simply foreign to the chord, which this
36
+ * single-pitch query cannot tell from a colour tone. The root locks the chord
37
+ * identity, the third locks its quality, and everything else is free voicing.
38
+ * Where a chord has no third, the tone standing in its place — the fourth of a
39
+ * `sus4`, the second of a `sus2`, the eleventh of an eleventh chord — takes the
40
+ * third's slot and is locked to `quality`, since moving it changes the chord.
41
+ * At most one interval class of a chord is ever reported as its third, so a
42
+ * consumer reading `lock: 'quality'` as "this tone identifies the chord" gets
43
+ * one answer rather than two. Detecting an octave doubling requires the
44
+ * surrounding voicing, which this query does not carry, so `'doubling'` is part
45
+ * of the type — the shared vocabulary of harmonic roles — but is never returned
46
+ * here.
47
+ *
48
+ * @param pitch MIDI pitch or bare pitch class.
49
+ * @param chord The chord providing the root reference, as a chord symbol, chord
50
+ * data, or a `Chord`.
51
+ * @param chordId Identifier stored on the result (defaults to 0).
52
+ * @returns The pitch's role, lock level, and owning chord id.
53
+ * @example
54
+ * ```ts
55
+ * import { roleOf, makeChord } from '@libraz/libcantus';
56
+ * roleOf(64, makeChord(0, 'maj')); // E over C major
57
+ * // { role: 'third', lock: 'quality', belongsToChordId: 0 }
58
+ * ```
59
+ * @category Functional Harmony
60
+ */
61
+ declare function roleOf(pitch: number, chord: ChordLike, chordId?: number): VoicedRole;
62
+
63
+ export { roleOf as r };
64
+ export type { HarmonyRole as H, LockLevel as L, VoicedRole as V };