note-mapper 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,281 @@
+# note-mapper
+
+Maps guitar notes from [note-listener](https://www.npmjs.com/package/note-listener) to scale degrees, intervals, and game actions.
+
+Use it to turn a guitar into a game controller — the player picks a key and scale, and their fretboard positions map to actions regardless of what key they're in.
+
+---
+
+## Installation
+
+```bash
+npm install note-mapper
+```
+
+`note-listener` should already be installed in your project as this package works alongside it.
+
+---
+
+## Quick Start
+
+```js
+import { createPitchListener } from "note-listener"
+import { createMapper, SCALES, ACTIONS_5 } from "note-mapper"
+
+const mapper = createMapper({
+  scale: SCALES["pentatonic_minor"]["A"],
+  degreeActions: ACTIONS_5,
+  onAction(action, meta) {
+    console.log(action) // "jump", "attack" etc
+    console.log(meta)   // { type, note, freq, degree, cents }
+  }
+})
+
+const listener = await createPitchListener({
+  onNotes(notes) {
+    mapper.process(notes)
+  }
+})
+
+listener.start()
+```
+
+---
+
+## Concepts
+
+### Scale degrees
+
+A scale degree is the position of a note within a scale — 0 is always the root.
+The player can switch key and the same fret positions produce the same actions.
+
+```
+A minor pentatonic: ["A", "C", "D", "E", "G"]
+                      0    1    2    3    4
+
+Play "A" → degree 0 → "jump"
+Play "E" → degree 3 → "attack"
+```
+
+### Intervals
+
+An interval is the distance in semitones between two notes played together.
+Used for two-note combinations like power chords triggering special moves.
+
+```
+Play A + E together → Perfect 5th (7 semitones) → "power_attack"
+```
+
+---
+
+## API
+
+### `createMapper(options)`
+
+Creates a mapper instance. Call `mapper.process(notes)` inside `onNotes`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `scale` | `string[]` | required | Scale array from `SCALES` |
+| `degreeActions` | `object` | `ACTIONS_7` | Maps degree → action string |
+| `intervalActions` | `object` | `ACTIONS_INTERVAL` | Maps semitones → action string |
+| `centsTolerance` | `number` | `40` | Cents off-pitch still accepted |
+| `intervalWindow` | `number` | `150` | Ms window for interval detection |
+| `onAction` | `function` | required | Fires when an action is detected |
+
+#### Returns
+
+```js
+{
+  process(notes),           // call this inside onNotes every frame
+  setScale(newScale),       // swap scale at runtime
+  setDegreeActions(map),    // swap degree actions at runtime
+  setIntervalActions(map),  // swap interval actions at runtime
+  getHeldNotes(),           // returns currently held notes
+}
+```
+
+---
+
+### `SCALES`
+
+All scales, keyed by type then root note.
+
+```js
+import { SCALES } from "note-mapper"
+
+SCALES["major"]["G"]              // G major
+SCALES["pentatonic_minor"]["E"]   // E minor pentatonic
+SCALES["dorian"]["A"]             // A dorian
+```
+
+**Available scale types:**
+
+| Key | Name | Notes |
+|---|---|---|
+| `major` | Major / Ionian | 7 |
+| `natural_minor` | Natural Minor / Aeolian | 7 |
+| `pentatonic_minor` | Minor Pentatonic | 5 |
+| `pentatonic_major` | Major Pentatonic | 5 |
+| `blues` | Blues | 6 |
+| `dorian` | Dorian | 7 |
+| `phrygian` | Phrygian | 7 |
+| `lydian` | Lydian | 7 |
+| `mixolydian` | Mixolydian | 7 |
+| `locrian` | Locrian | 7 |
+| `harmonic_minor` | Harmonic Minor | 7 |
+| `melodic_minor` | Melodic Minor | 7 |
+| `phrygian_dominant` | Phrygian Dominant | 7 |
+| `whole_tone` | Whole Tone | 6 |
+| `diminished` | Diminished | 8 |
+
+All scale types are available in all 12 keys: `C C# D Eb E F F# G Ab A Bb B`
+
+---
+
+### `KEYS`
+
+Array of all 12 root keys — useful for building a key selector UI.
+
+```js
+import { KEYS } from "note-mapper"
+// ["C", "C#", "D", "Eb", "E", "F", "F#", "G", "Ab", "A", "Bb", "B"]
+```
+
+---
+
+### Default action maps
+
+```js
+import { ACTIONS_5, ACTIONS_6, ACTIONS_7, ACTIONS_INTERVAL } from "note-mapper"
+```
+
+**`ACTIONS_5`** — for pentatonic scales (5 notes)
+
+| Degree | Action |
+|---|---|
+| 0 | jump |
+| 1 | move_left |
+| 2 | move_right |
+| 3 | attack |
+| 4 | shield |
+
+**`ACTIONS_6`** — for blues scale (6 notes)
+
+Adds `special` at degree 5.
+
+**`ACTIONS_7`** — for diatonic scales (7 notes)
+
+Adds `special` at degree 5 and `ultimate` at degree 6.
+
+**`ACTIONS_INTERVAL`** — for two-note combinations
+
+| Semitones | Interval | Action |
+|---|---|---|
+| 5 | Perfect 4th | special |
+| 7 | Perfect 5th | power_attack |
+| 3 | Minor 3rd | block |
+| 4 | Major 3rd | dodge |
+| 6 | Tritone | taunt |
+| 9 | Major 6th | heal |
+| 10 | Minor 7th | roll |
+| 12 | Octave | ultimate |
+
+---
+
+### Lower level utilities
+
+If you want more control than `createMapper` gives you, use these directly.
+
+```js
+import {
+  getDegree,
+  getDegreeWithTolerance,
+  degreeToNote,
+  isInScale,
+  getInterval,
+  getIntervalInfo,
+  detectInterval,
+  isInterval,
+} from "note-mapper"
+```
+
+**`getDegree(note, scale)`** — returns 0-based degree or null if not in scale
+
+```js
+getDegree("A2", ["A","C","D","E","G"]) // → 0
+getDegree("F2", ["A","C","D","E","G"]) // → null
+```
+
+**`getDegreeWithTolerance(note, freq, scale, centsTolerance?)`** — same but accepts slightly out of tune notes
+
+**`degreeToNote(degree, scale)`** — reverse lookup, degree → note name
+
+```js
+degreeToNote(3, ["A","C","D","E","G"]) // → "E"
+```
+
+**`isInScale(note, scale)`** — returns boolean
+
+**`getInterval(freqA, freqB)`** — returns semitone count 0–12
+
+```js
+getInterval(440, 660) // → 7 (perfect 5th)
+```
+
+**`getIntervalInfo(freqA, freqB)`** — returns full interval object
+
+```js
+getIntervalInfo(440, 660)
+// → { semitones: 7, name: "Perfect 5th", short: "P5", character: "power chord, strong" }
+```
+
+**`detectInterval(notes, history, windowMs?)`** — detects interval from onNotes array with timing window
+
+**`isInterval(semitones, short)`** — readable interval check
+
+```js
+isInterval(7, "P5") // → true
+```
+
+---
+
+## Custom action maps
+
+You can define your own action maps and swap them at runtime:
+
+```js
+const myActions = {
+  0: "fly",
+  1: "run_left",
+  2: "run_right",
+  3: "fireball",
+  4: "teleport",
+}
+
+mapper.setDegreeActions(myActions)
+
+// swap back later
+mapper.setDegreeActions(ACTIONS_5)
+```
+
+---
+
+## Switching scale at runtime
+
+```js
+// player changes key in settings
+mapper.setScale(SCALES["major"]["G"])
+
+// player changes scale type
+mapper.setScale(SCALES["dorian"]["A"])
+```
+
+Held notes and interval history are cleared automatically on scale change.
+
+---
+
+## License
+
+MIT © Donald Edwin
+ 

package/package.json

@@ -1,15 +1,22 @@
 {
   "name": "note-mapper",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Map guitar notes from note-listener to scale degrees, intervals and game actions",
   "main": "index.js",
   "exports": {
-        ".": "./src/index.js"
+    ".": "./src/index.js"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": ["guitar", "music", "pitch", "scale", "interval", "game-controller"],
+  "keywords": [
+    "guitar",
+    "music",
+    "pitch",
+    "scale",
+    "interval",
+    "game-controller"
+  ],
   "author": "Donald Edwin",
   "license": "MIT",
   "type": "module",