@audio/note 1.0.0

package/LICENSE

@@ -0,0 +1,40 @@
+Kṛṣnized
+
+This is a reminder that, in the absolute sense, all results of work belong to the Supreme.
+
+While software and intellectual property (IP) require a formal license to define authorship,
+responsibilities, or distribution limitations, these are temporary material designations.
+The origin and destination of all ideas, as well as the ultimate owner of all results,
+is the Supreme. The most meaningful action is to dedicate these results to the Supreme.
+This process is known as Karma-Yoga and is described in BG 3.9, BG 12.10 and BG 18.46.
+
+"Work done as a sacrifice for the Supreme must be performed;
+otherwise, work binds one to the material world."
+
+This license does not override or alter the terms specified by the material-level license below.
+
+ॐ
+
+---
+
+MIT License
+
+Copyright (c) Dmitry Iv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @audio/note
+
+> Music-theory primitives: Hz ↔ MIDI ↔ note name, cents, scales, snapping.
+
+```js
+import { hzToMidi, midiToHz, name, parse, cents, SCALES, snapMidi, snapHz } from '@audio/note'
+
+name(69)                          // 'A4'
+cents(443)                        // { midi: 69, name: 'A4', hz: 440, cents: 11.7 } — tuner readout
+snapHz(450, { scale: 'major' })   // nearest major-scale frequency
+```
+
+Hz/MIDI/name conversion + scale tables/snapping — one small, always-together substrate. Not a music-theory library (chords, keys, roman numerals): that's composition/notation tooling out of `@audio`'s audio-processing scope — see tonal.js/teoria.js for that. Used by `@audio/tune` (pitch correction), the tuner tool, and `@audio/midi`.

package/convert.js

@@ -0,0 +1,31 @@
+// Note math — Hz ↔ MIDI ↔ note name, cents offset. 12-TET, MIDI convention (C4 = 60, A4 = 69).
+
+export const NAMES_SHARP = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']
+export const NAMES_FLAT = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B']
+
+export const hzToMidi = (hz, a4 = 440) => 69 + 12 * Math.log2(hz / a4)
+export const midiToHz = (midi, a4 = 440) => a4 * 2 ** ((midi - 69) / 12)
+
+/** midi → 'C#4' (or 'Db4' with {flat: true}) */
+export function name (midi, { flat = false } = {}) {
+	let m = Math.round(midi)
+	let pc = ((m % 12) + 12) % 12
+	let oct = Math.floor(m / 12) - 1
+	return (flat ? NAMES_FLAT : NAMES_SHARP)[pc] + oct
+}
+
+/** 'A4' | 'C#3' | 'Bb2' → midi number */
+export function parse (str) {
+	let m = /^([A-Ga-g])([#b]?)(-?\d+)$/.exec(str.trim())
+	if (!m) throw new RangeError(`note: cannot parse "${str}"`)
+	const BASE = { C: 0, D: 2, E: 4, F: 5, G: 7, A: 9, B: 11 }
+	let pc = BASE[m[1].toUpperCase()] + (m[2] === '#' ? 1 : m[2] === 'b' ? -1 : 0)
+	return pc + (Number(m[3]) + 1) * 12
+}
+
+/** hz → { midi, name, hz (exact note), cents (offset from it) } — tuner readout */
+export function cents (hz, { a4 = 440, flat = false } = {}) {
+	let midi = Math.round(hzToMidi(hz, a4))
+	let ref = midiToHz(midi, a4)
+	return { midi, name: name(midi, { flat }), hz: ref, cents: 1200 * Math.log2(hz / ref) }
+}

package/index.js

@@ -0,0 +1,4 @@
+// @audio/note — Hz ↔ MIDI ↔ name/cents, scale tables, pitch snapping.
+
+export * from './convert.js'
+export * from './scale.js'

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@audio/note",
+  "version": "1.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Music-theory primitives — Hz ↔ MIDI ↔ name, cents, scales, pitch snapping",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "convert.js",
+    "scale.js"
+  ],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "devDependencies": {
+    "tst": "^9.4.0"
+  },
+  "keywords": [
+    "audio",
+    "music",
+    "note",
+    "midi",
+    "scale",
+    "tuner"
+  ],
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scale.js

@@ -0,0 +1,37 @@
+// Scales and pitch snapping — the tune-snap / tuner substrate.
+
+import { hzToMidi, midiToHz } from './convert.js'
+
+export const SCALES = {
+	chromatic: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
+	major: [0, 2, 4, 5, 7, 9, 11],
+	minor: [0, 2, 3, 5, 7, 8, 10],
+	'harmonic-minor': [0, 2, 3, 5, 7, 8, 11],
+	'melodic-minor': [0, 2, 3, 5, 7, 9, 11],
+	'pentatonic-major': [0, 2, 4, 7, 9],
+	'pentatonic-minor': [0, 3, 5, 7, 10],
+	blues: [0, 3, 5, 6, 7, 10],
+	dorian: [0, 2, 3, 5, 7, 9, 10],
+	mixolydian: [0, 2, 4, 5, 7, 9, 10],
+	whole: [0, 2, 4, 6, 8, 10],
+}
+
+/** snap a (possibly fractional) midi value to the nearest scale degree */
+export function snapMidi (midi, { scale = 'chromatic', root = 0 } = {}) {
+	let degrees = typeof scale === 'string' ? SCALES[scale] : scale
+	if (!degrees) throw new RangeError(`note: unknown scale "${scale}"`)
+	let best = 0, bestDist = Infinity
+	for (let oct = Math.floor(midi / 12) - 1; oct <= Math.floor(midi / 12) + 1; oct++) {
+		for (let d of degrees) {
+			let cand = oct * 12 + root + d
+			let dist = Math.abs(cand - midi)
+			if (dist < bestDist) { bestDist = dist; best = cand }
+		}
+	}
+	return best
+}
+
+/** snap a frequency to the nearest scale note frequency */
+export function snapHz (hz, { scale = 'chromatic', root = 0, a4 = 440 } = {}) {
+	return midiToHz(snapMidi(hzToMidi(hz, a4), { scale, root }), a4)
+}