zx-kit 0.26.0 → 0.27.0

package/README.md

@@ -572,6 +572,7 @@ requestAnimationFrame(loop)
 | [`font.ts`](#fontts--rom-bitmap-font) | 96-character ROM font, raw bitmap access |
 | [`i18n.ts`](#i18nts--runtime-locale-selection) | Type-safe runtime locale selection for translated string packs |
 | [`lighting.ts`](#lightingts--dithered-cave-darkness) | Dithered cave darkness: pre-baked level tiles + dirty-cell buffer, one blit/frame (no per-frame putImageData) |
+| [`music.ts`](#musicts--note-name-ay-music) | Write AY music by note name (`A5`, `C#4`) and loop it for background tracks |
 
 ---
 
@@ -2669,6 +2670,59 @@ The `darknessAt` callback is where you add **depth gradients** (darker the deepe
 
 ---
 
+## `music.ts` — Note-Name AY Music
+
+Write AY tunes by **note name** instead of raw frequencies, and **loop** them for
+background music. A thin, friendly layer over [`playAY`](#playaypattern-startdelay-void):
+the AY chip already plays three channels of `AYNote`s — this lets you *author* and
+*repeat* them without the maths (so "I don't read note tables" is no longer a blocker).
+
+### `noteToFreq(name): number`
+
+Note name → frequency (Hz), equal temperament, **A4 = 440**. Accepts `A5`, `C#4`,
+`Db3`, `Fs5` (`s` = sharp). `r` / `-` is a rest → `0` (a silent note). Throws on a
+malformed name. Pure.
+
+```ts
+noteToFreq('A4')   // 440
+noteToFreq('C4')   // 261.63  (middle C)
+noteToFreq('A5')   // 880
+```
+
+### `seq(spec, options?): AYNote[]`
+
+Parses a compact note string into one channel's `AYNote[]`. Tokens are
+whitespace-separated `Note` or `Note:durMs`; `r` (or `-`) is a rest. `options.dur`
+sets the default duration (200 ms); `options.noise` / `noisePeriod` mix LFSR noise
+into every note (handy for a texture/percussion channel).
+
+```ts
+seq('A4 C5:400 r:200 E5')          // A4 @default, C5 @400ms, rest @200ms, E5 @default
+seq('r r r r', { dur: 240, noise: true })   // a noise-only texture line
+```
+
+### `playAYLoop(pattern): { stop() }`
+
+Plays a 3-channel pattern **on repeat** — background music. Re-schedules each loop
+after the pattern's length (its longest channel) and returns a handle to `stop()`.
+No-ops (returns a do-nothing stop) when there's no audio context yet or the pattern
+is empty. Call after a user gesture has unlocked audio.
+
+```ts
+const track = playAYLoop({
+  a: seq('A4 C5 E5 C5', { dur: 240 }),         // melody
+  b: seq('A2:480 E2:480', { dur: 480 }),        // slow bass drone
+  c: seq('r r r r', { dur: 240, noise: true }), // texture
+})
+// later…
+track.stop()
+```
+
+> Looping re-schedules at the pattern boundary via a timer — fine for ambient /
+> background loops; for tight musical sync you'd want a sample-accurate scheduler.
+
+---
+
 ## Architecture
 
 ### Module structure

package/dist/index.d.ts

@@ -17,4 +17,5 @@ export * from './scene.js';
 export * from './save.js';
 export * from './i18n.js';
 export * from './lighting.js';
+export * from './music.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -17,4 +17,5 @@ export * from './scene.js';
 export * from './save.js';
 export * from './i18n.js';
 export * from './lighting.js';
+export * from './music.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA"}

package/dist/music.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @module music
+ *
+ * Write AY music by **note name** instead of raw frequencies, and **loop** it for
+ * background tracks. A thin, friendly layer over {@link playAY} (the AY chip
+ * already plays three channels of {@link AYNote}s — this just lets you author and
+ * repeat them without doing the maths).
+ *
+ * @example
+ * ```ts
+ * import { seq, playAYLoop, noteToFreq } from 'zx-kit'
+ *
+ * const loop = playAYLoop({
+ *   a: seq('A4 C5 E5 C5', { dur: 240 }),          // melody by name
+ *   b: seq('A2:480 E2:480', { dur: 480 }),         // slow bass drone
+ *   c: seq('r r r r', { dur: 240, noise: true }),  // a little texture
+ * })
+ * // later: loop.stop()
+ * ```
+ */
+import { type AYNote } from './ay.js';
+/**
+ * Note name → frequency (Hz), equal temperament, A4 = 440. Accepts `A5`, `C#4`,
+ * `Db3`, `Fs5` (`s` = sharp); `r` / `-` is a rest → `0` (a silent {@link AYNote}).
+ * Throws on a malformed name.
+ */
+export declare function noteToFreq(name: string): number;
+/** Options for {@link seq}. */
+export interface SeqOptions {
+    /** Default note duration in ms when a token doesn't specify one (default 200). */
+    dur?: number;
+    /** Mix LFSR noise into every note (e.g. for a percussive/texture channel). */
+    noise?: boolean;
+    /** Noise period when `noise` is set. */
+    noisePeriod?: number;
+}
+/**
+ * Parses a compact note string into an {@link AYNote} array for one channel.
+ * Tokens are whitespace-separated `Note` or `Note:durMs`; `r` (or `-`) is a rest.
+ *
+ * @example
+ * seq('A4 C5:400 r:200 E5')  // A4 @default, C5 @400ms, rest @200ms, E5 @default
+ */
+export declare function seq(spec: string, opts?: SeqOptions): AYNote[];
+/** A running looped track. Call {@link LoopHandle.stop} to end it. */
+export interface LoopHandle {
+    stop(): void;
+}
+/**
+ * Plays a 3-channel AY pattern on repeat — background music. Re-schedules each
+ * loop after the pattern's length (the longest channel). No-ops (returns a stop
+ * that does nothing) when there is no audio context yet or the pattern is empty.
+ *
+ * Call after the audio context is unlocked by a user gesture.
+ */
+export declare function playAYLoop(pattern: {
+    a?: AYNote[];
+    b?: AYNote[];
+    c?: AYNote[];
+}): LoopHandle;
+//# sourceMappingURL=music.d.ts.map

package/dist/music.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"music.d.ts","sourceRoot":"","sources":["../src/music.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,SAAS,CAAA;AAK7C;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW/C;AAED,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,MAAM,EAAE,CAajE;AAED,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,IAAI,IAAI,IAAI,CAAA;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,UAAU,CAa5F"}

package/dist/music.js

@@ -0,0 +1,89 @@
+/**
+ * @module music
+ *
+ * Write AY music by **note name** instead of raw frequencies, and **loop** it for
+ * background tracks. A thin, friendly layer over {@link playAY} (the AY chip
+ * already plays three channels of {@link AYNote}s — this just lets you author and
+ * repeat them without doing the maths).
+ *
+ * @example
+ * ```ts
+ * import { seq, playAYLoop, noteToFreq } from 'zx-kit'
+ *
+ * const loop = playAYLoop({
+ *   a: seq('A4 C5 E5 C5', { dur: 240 }),          // melody by name
+ *   b: seq('A2:480 E2:480', { dur: 480 }),         // slow bass drone
+ *   c: seq('r r r r', { dur: 240, noise: true }),  // a little texture
+ * })
+ * // later: loop.stop()
+ * ```
+ */
+import { playAY } from './ay.js';
+import { getAudioContext } from './audio.js';
+const SEMITONE = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 };
+/**
+ * Note name → frequency (Hz), equal temperament, A4 = 440. Accepts `A5`, `C#4`,
+ * `Db3`, `Fs5` (`s` = sharp); `r` / `-` is a rest → `0` (a silent {@link AYNote}).
+ * Throws on a malformed name.
+ */
+export function noteToFreq(name) {
+    const n = name.trim().toLowerCase();
+    if (n === 'r' || n === '-' || n === '')
+        return 0;
+    const m = /^([a-g])([#sb]?)(-?\d)$/.exec(n);
+    if (!m)
+        throw new Error(`noteToFreq: bad note "${name}" (expected e.g. A5, C#4, Bb3, or r)`);
+    let semis = SEMITONE[m[1]];
+    if (m[2] === '#' || m[2] === 's')
+        semis += 1;
+    else if (m[2] === 'b')
+        semis -= 1;
+    const octave = parseInt(m[3], 10);
+    const midi = (octave + 1) * 12 + semis; // C4 = MIDI 60, A4 = 69
+    return 440 * Math.pow(2, (midi - 69) / 12);
+}
+/**
+ * Parses a compact note string into an {@link AYNote} array for one channel.
+ * Tokens are whitespace-separated `Note` or `Note:durMs`; `r` (or `-`) is a rest.
+ *
+ * @example
+ * seq('A4 C5:400 r:200 E5')  // A4 @default, C5 @400ms, rest @200ms, E5 @default
+ */
+export function seq(spec, opts = {}) {
+    const defDur = opts.dur ?? 200;
+    const out = [];
+    for (const tok of spec.split(/\s+/).filter(Boolean)) {
+        const [name, durStr] = tok.split(':');
+        const note = { freq: noteToFreq(name), dur: durStr ? Number(durStr) : defDur };
+        if (opts.noise) {
+            note.noise = true;
+            if (opts.noisePeriod !== undefined)
+                note.noisePeriod = opts.noisePeriod;
+        }
+        out.push(note);
+    }
+    return out;
+}
+/**
+ * Plays a 3-channel AY pattern on repeat — background music. Re-schedules each
+ * loop after the pattern's length (the longest channel). No-ops (returns a stop
+ * that does nothing) when there is no audio context yet or the pattern is empty.
+ *
+ * Call after the audio context is unlocked by a user gesture.
+ */
+export function playAYLoop(pattern) {
+    if (!getAudioContext())
+        return { stop() { } };
+    const total = (ns) => (ns ? ns.reduce((s, n) => s + n.dur, 0) : 0);
+    const loopMs = Math.max(total(pattern.a), total(pattern.b), total(pattern.c));
+    if (loopMs <= 0)
+        return { stop() { } };
+    playAY(pattern);
+    const id = setInterval(() => playAY(pattern), loopMs);
+    return {
+        stop() {
+            clearInterval(id);
+        },
+    };
+}
+//# sourceMappingURL=music.js.map

package/dist/music.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"music.js","sourceRoot":"","sources":["../src/music.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zx-kit",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/zrebec/zx-kit.git"