@vibuca/synth8-core 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sven Hemmer
+
+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,124 @@
+# @vibuca/synth8-core
+
+Core parser and compiler for Synt8, an MIT-licensed pattern music toolkit written in TypeScript.
+
+Synt8 defines its own small pattern DSL for rhythmic and melodic music patterns.
+
+## Install
+
+```bash
+npm install @vibuca/synth8-core
+```
+
+## Usage
+
+```ts
+import { compile } from "@vibuca/synth8-core";
+
+const pattern = compile(`
+  song(
+    beat("kick+hihat snare hihat snare"),
+    melody("c4 e4 g4 _")
+  )
+`);
+
+console.log(pattern);
+```
+
+## Supported syntax
+
+### Beat patterns
+
+```ts
+beat("kick snare hihat hihat")
+```
+
+### Melody patterns
+
+```ts
+melody("c4 e4 g4 _")
+```
+
+### Songs
+
+```ts
+song(
+  beat("kick snare"),
+  melody("c4 e4")
+)
+```
+
+### Rate
+
+```ts
+beat("kick snare").rate(2)
+melody("c4 e4 g4").rate(2)
+```
+
+### Rests
+
+```ts
+beat("kick _ snare hihat")
+melody("c4 _ e4 g4")
+```
+
+### Groups
+
+```ts
+beat("kick [snare hihat] kick")
+melody("c4 [e4 g4] c5")
+```
+
+### Parallel drum hits
+
+```ts
+beat("kick+hihat snare hihat snare")
+```
+
+## Output
+
+`compile()` returns a pattern:
+
+```ts
+type Pattern = {
+  length: number;
+  events: Event[];
+};
+```
+
+Events are stored in beats, not seconds.
+
+```ts
+type Event =
+  | {
+      time: number;
+      dur: number;
+      type: "drum";
+      value: string;
+    }
+  | {
+      time: number;
+      dur: number;
+      type: "note";
+      value: string;
+    };
+```
+
+## Supported drum sounds
+
+```txt
+kick
+snare
+clap
+hihat
+openhat
+tom
+rim
+cowbell
+```
+
+Use `_` for rests.
+
+## License
+
+MIT

package/dist/compiler/compiler.d.ts

@@ -0,0 +1,2 @@
+import { Pattern } from '../model';
+export declare const compile: (source: string) => Pattern;

package/dist/compiler/index.d.ts

@@ -0,0 +1 @@
+export * from './compiler';

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export declare const VERSION = "0.1.0";
+export * from './compiler';
+export * from './parser';
+export * from './model';

package/dist/index.js

@@ -0,0 +1,302 @@
+//#region src/parser/beat-pattern-parser.ts
+var e = (e) => {
+	let t = e.split("+").filter(Boolean);
+	return t.length === 1 ? {
+		kind: "BeatSound",
+		value: t[0]
+	} : {
+		kind: "BeatParallel",
+		sounds: t.map((e) => ({
+			kind: "BeatSound",
+			value: e
+		}))
+	};
+}, t = (t) => {
+	let n = 0, r = (i) => {
+		let a = [];
+		for (; n < t.length;) {
+			let o = t[n];
+			if (/\s/.test(o)) {
+				n++;
+				continue;
+			}
+			if (i && o === i) return n++, a;
+			if (o === "[") {
+				n++, a.push({
+					kind: "BeatGroup",
+					steps: r("]")
+				});
+				continue;
+			}
+			if (o === "]") throw Error("Unexpected closing group ']'.");
+			let s = "";
+			for (; n < t.length && !/\s/.test(t[n]) && t[n] !== "[" && t[n] !== "]";) s += t[n], n++;
+			s.length > 0 && a.push(e(s));
+		}
+		if (i) throw Error("Unterminated group '['.");
+		return a;
+	};
+	return r();
+}, n = /^[a-gA-G](#|b)?[0-8]$/, r = (e) => e === "_" || n.test(e);
+//#endregion
+//#region src/parser/melody-pattern-parser.ts
+function i(e) {
+	let t = [...e], n = 0;
+	function i() {
+		for (; t[n] === " ";) n++;
+	}
+	function a(e) {
+		let o = [];
+		for (; n < t.length;) {
+			if (i(), e && t[n] === e) return n++, o;
+			if (t[n] === "[") {
+				n++, o.push({
+					kind: "MelodyGroup",
+					notes: a("]")
+				});
+				continue;
+			}
+			let s = "";
+			for (; n < t.length && t[n] !== " " && t[n] !== "[" && t[n] !== "]";) s += t[n++];
+			if (!s) break;
+			if (!r(s)) throw Error(`Unknown note: ${s}`);
+			o.push({
+				kind: "MelodyNote",
+				value: s
+			});
+		}
+		if (e) throw Error("Unclosed melody group");
+		return o;
+	}
+	return a();
+}
+//#endregion
+//#region src/parser/tokenizer.ts
+var a = (e) => {
+	let t = [], n = 0;
+	for (; n < e.length;) {
+		let r = e[n];
+		if (/\s/.test(r)) {
+			n++;
+			continue;
+		}
+		if (/[a-zA-Z_]/.test(r)) {
+			let r = "";
+			for (; /[a-zA-Z0-9_]/.test(e[n] ?? "");) r += e[n], n++;
+			t.push({
+				type: "identifier",
+				value: r
+			});
+			continue;
+		}
+		if (r === "\"") {
+			n++;
+			let r = "";
+			for (; n < e.length && e[n] !== "\"";) r += e[n], n++;
+			if (e[n] !== "\"") throw Error("Unterminated string literal.");
+			n++, t.push({
+				type: "string",
+				value: r
+			});
+			continue;
+		}
+		if (/\d/.test(r)) {
+			let r = "";
+			for (; /[\d.]/.test(e[n] ?? "");) r += e[n], n++;
+			t.push({
+				type: "number",
+				value: Number(r)
+			});
+			continue;
+		}
+		if (r === "(" || r === ")" || r === "." || r === ",") {
+			t.push({
+				type: "symbol",
+				value: r
+			}), n++;
+			continue;
+		}
+		throw Error(`Unexpected character: ${r}`);
+	}
+	return t;
+}, o = class {
+	tokens;
+	index = 0;
+	constructor(e) {
+		this.tokens = e;
+	}
+	parse() {
+		let e = this.parseExpression();
+		if (!this.isAtEnd()) throw Error("Unexpected tokens after expression.");
+		return e;
+	}
+	parseExpression() {
+		let e = this.peek();
+		if (e?.type !== "identifier") throw Error("Expected expression.");
+		if (e.value === "beat") return this.parseBeatExpression();
+		if (e.value === "melody") return this.parseMelodyExpression();
+		if (e.value === "song") return this.parseSongExpression();
+		throw Error(`Unknown expression: ${e.value}`);
+	}
+	parseOptionalRate() {
+		let e = 1;
+		if (this.matchSymbol(".") && (this.expectIdentifier("rate"), this.expectSymbol("("), e = this.expectNumber(), this.expectSymbol(")")), !Number.isFinite(e) || e <= 0) throw Error(`Invalid rate: ${e}`);
+		return e;
+	}
+	parseBeatExpression() {
+		this.expectIdentifier("beat"), this.expectSymbol("(");
+		let e = this.expectString();
+		this.expectSymbol(")");
+		let n = this.parseOptionalRate();
+		return {
+			kind: "BeatExpression",
+			steps: t(e),
+			rate: n
+		};
+	}
+	parseMelodyExpression() {
+		this.expectIdentifier("melody"), this.expectSymbol("(");
+		let e = this.expectString();
+		this.expectSymbol(")");
+		let t = this.parseOptionalRate();
+		return {
+			kind: "MelodyExpression",
+			notes: i(e),
+			rate: t
+		};
+	}
+	parseSongExpression() {
+		this.expectIdentifier("song"), this.expectSymbol("(");
+		let e = [];
+		if (!this.matchSymbol(")")) {
+			do
+				e.push(this.parseExpression());
+			while (this.matchSymbol(","));
+			this.expectSymbol(")");
+		}
+		if (e.length === 0) throw Error("song() requires at least one track.");
+		return {
+			kind: "SongExpression",
+			tracks: e
+		};
+	}
+	expectIdentifier(e) {
+		let t = this.advance();
+		if (t?.type !== "identifier" || t.value !== e) throw Error(`Expected identifier "${e}".`);
+	}
+	expectString() {
+		let e = this.advance();
+		if (e?.type !== "string") throw Error("Expected string.");
+		return e.value;
+	}
+	expectNumber() {
+		let e = this.advance();
+		if (e?.type !== "number") throw Error("Expected number.");
+		return e.value;
+	}
+	expectSymbol(e) {
+		let t = this.advance();
+		if (t?.type !== "symbol" || t.value !== e) throw Error(`Expected "${e}".`);
+	}
+	matchSymbol(e) {
+		let t = this.peek();
+		return t?.type === "symbol" && t.value === e ? (this.advance(), !0) : !1;
+	}
+	advance() {
+		return this.tokens[this.index++];
+	}
+	peek() {
+		return this.tokens[this.index];
+	}
+	isAtEnd() {
+		return this.index >= this.tokens.length;
+	}
+}, s = (e) => new o(a(e)).parse(), c = "_", l = new Set([
+	"kick",
+	"snare",
+	"clap",
+	"hihat",
+	"openhat",
+	"tom",
+	"rim",
+	"cowbell"
+]), u = (e) => {
+	if (e !== c && !l.has(e)) throw Error(`Unknown drum sound: ${e}`);
+}, d = (e) => {
+	if (e.kind === "BeatGroup") {
+		for (let t of e.steps) d(t);
+		return;
+	}
+	if (e.kind === "BeatParallel") {
+		for (let t of e.sounds) u(t.value);
+		return;
+	}
+	u(e.value);
+}, f = (e, t, n) => {
+	if (e.length === 0) return [];
+	let r = [], i = n / e.length;
+	return e.forEach((e, n) => {
+		let a = t + n * i;
+		switch (e.kind) {
+			case "BeatGroup":
+				r.push(...f(e.steps, a, i));
+				break;
+			case "BeatParallel":
+				for (let t of e.sounds) t.value !== c && r.push({
+					time: a,
+					dur: i,
+					type: "drum",
+					value: t.value
+				});
+				break;
+			case "BeatSound":
+				if (e.value === c) break;
+				r.push({
+					time: a,
+					dur: i,
+					type: "drum",
+					value: e.value
+				});
+				break;
+		}
+	}), r;
+}, p = (e) => {
+	switch (e.kind) {
+		case "BeatExpression": {
+			for (let t of e.steps) d(t);
+			let t = 1 / e.rate, n = e.steps.length * t;
+			return {
+				length: n,
+				events: f(e.steps, 0, n)
+			};
+		}
+		case "MelodyExpression": {
+			let t = 1 / e.rate, n = e.notes.length * t;
+			return {
+				length: n,
+				events: m(e.notes, 0, n)
+			};
+		}
+		case "SongExpression": {
+			let t = e.tracks.map(p);
+			return {
+				length: Math.max(...t.map((e) => e.length)),
+				events: t.flatMap((e) => e.events)
+			};
+		}
+		default: throw Error("Unknown AST node");
+	}
+}, m = (e, t, n) => {
+	let r = n / e.length;
+	return e.flatMap((e, n) => {
+		let i = t + n * r;
+		return e.kind === "MelodyNote" ? e.value === "_" ? [] : [{
+			time: i,
+			dur: r,
+			type: "note",
+			value: e.value
+		}] : m(e.notes, i, r);
+	});
+}, h = (e) => p(s(e)), g = "0.1.0";
+//#endregion
+export { g as VERSION, h as compile, s as parse, a as tokenize };

package/dist/model/ast.d.ts

@@ -0,0 +1,37 @@
+export type AstNode = BeatExpression | MelodyExpression | SongExpression;
+export type BeatExpression = {
+    kind: "BeatExpression";
+    steps: BeatStep[];
+    rate: number;
+};
+export type SongExpression = {
+    kind: "SongExpression";
+    tracks: AstNode[];
+};
+export type MelodyExpression = {
+    kind: "MelodyExpression";
+    notes: MelodyStep[];
+    rate: number;
+};
+export type MelodyStep = MelodyNote | MelodyGroup;
+export type MelodyNote = {
+    kind: "MelodyNote";
+    value: string;
+};
+export type MelodyGroup = {
+    kind: "MelodyGroup";
+    notes: MelodyStep[];
+};
+export type BeatStep = BeatSound | BeatGroup | BeatParallel;
+export type BeatSound = {
+    kind: "BeatSound";
+    value: string;
+};
+export type BeatGroup = {
+    kind: "BeatGroup";
+    steps: BeatStep[];
+};
+export type BeatParallel = {
+    kind: "BeatParallel";
+    sounds: BeatSound[];
+};

package/dist/model/event.d.ts

@@ -0,0 +1,7 @@
+export type EventType = 'drum' | 'note';
+export type Event = {
+    time: number;
+    dur: number;
+    type: EventType;
+    value: string;
+};

package/dist/model/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ast';
+export * from './event';
+export * from './pattern';

package/dist/model/pattern.d.ts

@@ -0,0 +1,5 @@
+import { Event } from './event';
+export type Pattern = {
+    length: number;
+    events: Event[];
+};

package/dist/parser/beat-pattern-parser.d.ts

@@ -0,0 +1,2 @@
+import { BeatStep } from '../model/ast';
+export declare const parseBeatPattern: (source: string) => BeatStep[];

package/dist/parser/index.d.ts

@@ -0,0 +1,2 @@
+export * from './parser';
+export * from './tokenizer';

package/dist/parser/melody-pattern-parser.d.ts

@@ -0,0 +1,2 @@
+import { MelodyStep } from '../model/ast';
+export declare function parseMelodyPattern(source: string): MelodyStep[];

package/dist/parser/notes.d.ts

@@ -0,0 +1 @@
+export declare const isSupportedNote: (value: string) => boolean;

package/dist/parser/parser.d.ts

@@ -0,0 +1,2 @@
+import { AstNode } from '../model/ast';
+export declare const parse: (source: string) => AstNode;

package/dist/parser/tokenizer.d.ts

@@ -0,0 +1,14 @@
+export type Token = {
+    type: "identifier";
+    value: string;
+} | {
+    type: "string";
+    value: string;
+} | {
+    type: "number";
+    value: number;
+} | {
+    type: "symbol";
+    value: '(' | ')' | '.' | ',';
+};
+export declare const tokenize: (source: string) => Token[];

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@vibuca/synth8-core",
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run"
+  }
+}