music-jsx-compiler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 music-jsx-compiler contributors
+
+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,127 @@
+# music-jsx-compiler
+
+**Write chord charts in JSX. Get MusicXML out.**
+
+A tiny component framework for building MusicXML from familiar-looking JSX — loops, sections, and chord bars instead of hundreds of lines of XML. Built for humans *and* the LLMs that help them write music.
+
+```bash
+npm install music-jsx-compiler
+```
+
+---
+
+## Why this exists
+
+MusicXML is precise, but verbose. An eight-bar verse with four chords per bar can balloon into hundreds of lines — painful to write by hand and expensive to generate with AI.
+
+With **music-jsx-compiler**, you describe structure once and let the compiler expand it:
+
+```tsx
+<Song tempo={120} key="C" time="4/4">
+  <Loop times={8}>
+    <ChordBar chords={["Am", "F", "C", "G"]} />
+  </Loop>
+  <Bridge>
+    <Comment text="only guitar for the 2 next bars!" />
+    <ChordBar chords={["Dm", "G", "Em", "Am"]} />
+  </Bridge>
+</Song>
+```
+
+That becomes **9 measures** (8 looped bars + 1 bridge) of valid **MusicXML 4.0** with harmony symbols, rehearsal marks, and directions — roughly **10× fewer tokens** than writing the XML yourself.
+
+---
+
+## Quick start
+
+**1. Install**
+
+```bash
+npm install music-jsx-compiler
+```
+
+**2. Configure TypeScript** (so `.tsx` files use this JSX runtime)
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "music-jsx-compiler"
+  }
+}
+```
+
+**3. Write a song**
+
+```tsx
+import { Song, Loop, ChordBar, Words, compileToMusicXml } from "music-jsx-compiler";
+
+const song = (
+  <Song tempo={120} key="C" time="4/4" title="My Song">
+    <Loop times={4}>
+      <Words text="Guitar should start playing here" />
+      <ChordBar chords={["C", "G", "Am", "F"]} />
+    </Loop>
+  </Song>
+);
+
+const musicXml = compileToMusicXml(song);
+// → valid MusicXML string, ready to save or import into notation software
+```
+
+---
+
+## Components
+
+| Component | What it does |
+|-----------|--------------|
+| `Song` | Root element — set `tempo`, `key`, `time`, and optional `title` |
+| `Loop` | Repeat its children `times` |
+| `ChordBar` | One measure of chords — array length must match the beat count (e.g. 4 chords in 4/4) |
+| `Bridge` | Section wrapper (adds a rehearsal mark; defaults to "Bridge") |
+| `Section` | Named section wrapper with a custom `name` |
+| `Words` | Lyric or direction text above the next bar |
+| `Comment` | Rehearsal or performance note attached to the next bar |
+
+---
+
+## Chord symbols
+
+Common notation just works:
+
+`C` · `Am` · `F#m` · `Bb` · `G/B` · `Dm7` · `Cmaj7` · `Gsus4` · `Bdim` · `Caug` · and more
+
+---
+
+## Try the example
+
+Clone the repo and run:
+
+```bash
+npm install
+npm run example   # writes examples/output.musicxml
+```
+
+---
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `compileToMusicXml(tree)` | Compile a JSX song tree to a MusicXML string |
+| `Song`, `Loop`, `Bridge`, `Section`, `ChordBar`, `Words`, `Comment` | JSX components |
+| `parseChord(symbol)` | Parse a chord string into structured parts |
+| `flattenSong(tree)` | Expand loops/sections into a flat measure list |
+
+---
+
+## Requirements
+
+- **Node.js** 18+
+- **TypeScript** recommended (for `.tsx` and `jsxImportSource`)
+
+---
+
+## License
+
+MIT

package/dist/chord-parser.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedChord } from "./types.js";
+export declare function parseChord(symbol: string): ParsedChord;

package/dist/chord-parser.js

@@ -0,0 +1,68 @@
+const STEP_PATTERN = /^([A-G])([#b]?)/;
+const SLASH_PATTERN = /\/([A-G])([#b]?)$/;
+const KIND_ALIASES = {
+    "": { kind: "major", text: "" },
+    m: { kind: "minor", text: "m" },
+    min: { kind: "minor", text: "m" },
+    maj: { kind: "major", text: "maj" },
+    M: { kind: "major", text: "" },
+    "7": { kind: "dominant", text: "7" },
+    maj7: { kind: "major-seventh", text: "maj7" },
+    M7: { kind: "major-seventh", text: "maj7" },
+    m7: { kind: "minor-seventh", text: "m7" },
+    min7: { kind: "minor-seventh", text: "m7" },
+    dim: { kind: "diminished", text: "dim" },
+    o: { kind: "diminished", text: "dim" },
+    aug: { kind: "augmented", text: "aug" },
+    "+": { kind: "augmented", text: "+" },
+    sus2: { kind: "suspended-second", text: "sus2" },
+    sus4: { kind: "suspended-fourth", text: "sus4" },
+    sus: { kind: "suspended-fourth", text: "sus4" },
+    add9: { kind: "major", text: "add9" },
+    "6": { kind: "major-sixth", text: "6" },
+    m6: { kind: "minor-sixth", text: "m6" },
+    "9": { kind: "dominant-ninth", text: "9" },
+    m9: { kind: "minor-ninth", text: "m9" },
+    "11": { kind: "dominant-11th", text: "11" },
+    "13": { kind: "dominant-13th", text: "13" },
+};
+export function parseChord(symbol) {
+    const trimmed = symbol.trim();
+    if (!trimmed) {
+        throw new Error("Empty chord symbol");
+    }
+    const slashMatch = trimmed.match(SLASH_PATTERN);
+    const head = slashMatch ? trimmed.slice(0, -slashMatch[0].length) : trimmed;
+    const bass = slashMatch ? parsePitch(slashMatch[1], slashMatch[2]) : undefined;
+    const rootMatch = head.match(STEP_PATTERN);
+    if (!rootMatch) {
+        throw new Error(`Invalid chord symbol: ${symbol}`);
+    }
+    const root = parsePitch(rootMatch[1], rootMatch[2]);
+    const qualityText = head.slice(rootMatch[0].length);
+    const alias = KIND_ALIASES[qualityText];
+    if (!alias) {
+        throw new Error(`Unsupported chord quality "${qualityText}" in ${symbol}`);
+    }
+    const kindText = buildKindText(root.step, root.alter, alias.text, bass?.step, bass?.alter);
+    return {
+        symbol: trimmed,
+        rootStep: root.step,
+        rootAlter: root.alter,
+        kind: alias.kind,
+        kindText,
+        bassStep: bass?.step,
+        bassAlter: bass?.alter,
+    };
+}
+function parsePitch(step, accidental) {
+    const alter = accidental === "#" ? 1 : accidental === "b" ? -1 : 0;
+    return { step, alter };
+}
+function buildKindText(rootStep, rootAlter, quality, bassStep, bassAlter) {
+    const root = rootStep + (rootAlter === 1 ? "#" : rootAlter === -1 ? "b" : "");
+    const bass = bassStep === undefined
+        ? ""
+        : `/${bassStep}${bassAlter === 1 ? "#" : bassAlter === -1 ? "b" : ""}`;
+    return `${root}${quality}${bass}`;
+}

package/dist/compile.d.ts

@@ -0,0 +1,2 @@
+import type { MusicNode } from "./types.js";
+export declare function compileToMusicXml(root: MusicNode): string;

package/dist/compile.js

@@ -0,0 +1,98 @@
+import { chordDuration, escapeXml, flattenSong, renderHarmony, renderWords, validateMeasures, } from "./flatten.js";
+import { keySignatureFifths } from "./key-signature.js";
+const DIVISIONS = 4;
+export function compileToMusicXml(root) {
+    const { settings, measures } = flattenSong(root);
+    validateMeasures(settings, measures);
+    let previousSection;
+    const measureXml = measures
+        .map((measure, index) => {
+        const showSection = measure.section !== undefined && measure.section !== previousSection;
+        if (measure.section !== undefined) {
+            previousSection = measure.section;
+        }
+        return renderMeasure(measure, index, settings, showSection);
+    })
+        .join("\n");
+    const title = settings.title ?? "Untitled";
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE score-partwise PUBLIC "-//Recordare//DTD MusicXML 4.0 Partwise//EN" "http://www.musicxml.org/dtds/partwise.dtd">
+<score-partwise version="4.0">
+  <work>
+    <work-title>${escapeXml(title)}</work-title>
+  </work>
+  <part-list>
+    <score-part id="P1">
+      <part-name>Chords</part-name>
+    </score-part>
+  </part-list>
+  <part id="P1">
+${measureXml}
+  </part>
+</score-partwise>
+`;
+}
+function renderMeasure(measure, index, settings, showSection) {
+    const measureNumber = index + 1;
+    const attributes = index === 0
+        ? `
+      <attributes>
+        <divisions>${DIVISIONS}</divisions>
+        <key>
+          <fifths>${keySignatureFifths(settings.key)}</fifths>
+        </key>
+        <time>
+          <beats>${settings.beatsPerMeasure}</beats>
+          <beat-type>${settings.beatType}</beat-type>
+        </time>
+      </attributes>
+      <direction placement="above">
+        <direction-type>
+          <metronome>
+            <beat-unit>quarter</beat-unit>
+            <per-minute>${settings.tempo}</per-minute>
+          </metronome>
+        </direction-type>
+        <sound tempo="${settings.tempo}"/>
+      </direction>`
+        : "";
+    const sectionMark = showSection
+        ? `
+      <direction placement="above">
+        <direction-type>
+          <rehearsal>${escapeXml(measure.section)}</rehearsal>
+        </direction-type>
+      </direction>`
+        : "";
+    const comment = measure.comment ? `\n    <!-- ${escapeXml(measure.comment)} -->` : "";
+    const words = measure.words ? `\n${renderWords(measure.words)}` : "";
+    const duration = chordDuration(settings, DIVISIONS);
+    const harmonies = measure.chords
+        .map((chord) => `${renderHarmony(chord)}
+      <note>
+        <rest/>
+        <duration>${duration}</duration>
+        <voice>1</voice>
+        <type>${noteType(settings.beatType)}</type>
+      </note>`)
+        .join("\n");
+    const restOnly = harmonies ||
+        `      <note><rest/><duration>${DIVISIONS * settings.beatsPerMeasure}</duration><voice>1</voice><type>whole</type></note>`;
+    return `    <measure number="${measureNumber}">${comment}${attributes}${sectionMark}${words}
+${restOnly}
+    </measure>`;
+}
+function noteType(beatType) {
+    switch (beatType) {
+        case 1:
+            return "whole";
+        case 2:
+            return "half";
+        case 4:
+            return "quarter";
+        case 8:
+            return "eighth";
+        default:
+            return "quarter";
+    }
+}

package/dist/components.d.ts

@@ -0,0 +1,29 @@
+import type { SongNode, LoopNode, SectionNode, ChordBarNode, CommentNode, WordsNode } from "./types.js";
+export declare function Song(props: {
+    tempo: number;
+    key: string;
+    time: `${number}/${number}`;
+    title?: string;
+    children?: SongNode["children"] | SongNode["children"][number];
+}): SongNode;
+export declare function Loop(props: {
+    times: number;
+    children?: LoopNode["children"] | LoopNode["children"][number];
+}): LoopNode;
+export declare function Bridge(props: {
+    name?: string;
+    children?: SectionNode["children"] | SectionNode["children"][number];
+}): SectionNode;
+export declare function Section(props: {
+    name: string;
+    children?: SectionNode["children"] | SectionNode["children"][number];
+}): SectionNode;
+export declare function ChordBar(props: {
+    chords: string[];
+}): ChordBarNode;
+export declare function Comment(props: {
+    text: string;
+}): CommentNode;
+export declare function Words(props: {
+    text: string;
+}): WordsNode;

package/dist/components.js

@@ -0,0 +1,41 @@
+import { collectChildren } from "./jsx-runtime.js";
+export function Song(props) {
+    return {
+        type: "song",
+        tempo: props.tempo,
+        key: props.key,
+        time: props.time,
+        title: props.title,
+        children: collectChildren(props.children),
+    };
+}
+export function Loop(props) {
+    return {
+        type: "loop",
+        times: props.times,
+        children: collectChildren(props.children),
+    };
+}
+export function Bridge(props) {
+    return {
+        type: "section",
+        name: props.name ?? "Bridge",
+        children: collectChildren(props.children),
+    };
+}
+export function Section(props) {
+    return {
+        type: "section",
+        name: props.name,
+        children: collectChildren(props.children),
+    };
+}
+export function ChordBar(props) {
+    return { type: "chordBar", chords: props.chords };
+}
+export function Comment(props) {
+    return { type: "comment", text: props.text };
+}
+export function Words(props) {
+    return { type: "words", text: props.text };
+}

package/dist/flatten.d.ts

@@ -0,0 +1,10 @@
+import type { FlatMeasure, MusicNode, ParsedChord, SongSettings } from "./types.js";
+export declare function flattenSong(root: MusicNode): {
+    settings: SongSettings;
+    measures: FlatMeasure[];
+};
+export declare function validateMeasures(settings: SongSettings, measures: FlatMeasure[]): void;
+export declare function chordDuration(settings: SongSettings, divisions: number): number;
+export declare function escapeXml(text: string): string;
+export declare function renderWords(text: string): string;
+export declare function renderHarmony(chord: ParsedChord): string;

package/dist/flatten.js

@@ -0,0 +1,91 @@
+import { parseChord } from "./chord-parser.js";
+export function flattenSong(root) {
+    if (root.type !== "song") {
+        throw new Error("Root element must be <Song>");
+    }
+    const [beatsPerMeasure, beatType] = root.time.split("/").map(Number);
+    const settings = {
+        tempo: root.tempo,
+        key: root.key,
+        beatsPerMeasure,
+        beatType,
+        title: root.title,
+    };
+    const measures = [];
+    flattenNodes(root.children, measures);
+    return { settings, measures };
+}
+function flattenNodes(nodes, measures, section) {
+    let pendingComment;
+    let pendingWords;
+    for (const node of nodes) {
+        switch (node.type) {
+            case "loop":
+                for (let index = 0; index < node.times; index++) {
+                    flattenNodes(node.children, measures, section);
+                }
+                break;
+            case "section":
+                flattenNodes(node.children, measures, node.name);
+                break;
+            case "chordBar":
+                measures.push({
+                    chords: node.chords.map(parseChord),
+                    section,
+                    comment: pendingComment,
+                    words: pendingWords,
+                });
+                pendingComment = undefined;
+                pendingWords = undefined;
+                break;
+            case "comment":
+                pendingComment = node.text;
+                break;
+            case "words":
+                pendingWords = node.text;
+                break;
+            default:
+                throw new Error(`Unexpected node in flatten: ${node.type}`);
+        }
+    }
+}
+export function validateMeasures(settings, measures) {
+    for (const [index, measure] of measures.entries()) {
+        if (measure.chords.length === 0)
+            continue;
+        if (measure.chords.length !== settings.beatsPerMeasure) {
+            throw new Error(`Measure ${index + 1}: expected ${settings.beatsPerMeasure} chords for ${settings.beatsPerMeasure}/${settings.beatType}, got ${measure.chords.length}`);
+        }
+    }
+}
+export function chordDuration(settings, divisions) {
+    return Math.round((divisions * 4) / settings.beatType);
+}
+export function escapeXml(text) {
+    return text
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+export function renderWords(text) {
+    return `      <direction placement="above">
+        <direction-type>
+          <words>${escapeXml(text)}</words>
+        </direction-type>
+      </direction>`;
+}
+export function renderHarmony(chord) {
+    const rootAlter = chord.rootAlter === 0 ? "" : `\n          <root-alter>${chord.rootAlter}</root-alter>`;
+    const bass = chord.bassStep === undefined
+        ? ""
+        : `\n        <bass>\n          <bass-step>${chord.bassStep}</bass-step>${chord.bassAlter && chord.bassAlter !== 0
+            ? `\n          <bass-alter>${chord.bassAlter}</bass-alter>`
+            : ""}\n        </bass>`;
+    return `      <harmony>
+        <root>
+          <root-step>${chord.rootStep}</root-step>${rootAlter}
+        </root>
+        <kind text="${escapeXml(chord.kindText)}">${chord.kind}</kind>${bass}
+      </harmony>`;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type * from "./types.js";
+export { jsx, jsxs, Fragment } from "./jsx-runtime.js";
+export { Song, Loop, Bridge, Section, ChordBar, Comment, Words } from "./components.js";
+export { compileToMusicXml } from "./compile.js";
+export { parseChord } from "./chord-parser.js";
+export { flattenSong } from "./flatten.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { jsx, jsxs, Fragment } from "./jsx-runtime.js";
+export { Song, Loop, Bridge, Section, ChordBar, Comment, Words } from "./components.js";
+export { compileToMusicXml } from "./compile.js";
+export { parseChord } from "./chord-parser.js";
+export { flattenSong } from "./flatten.js";

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,11 @@
+import type { MusicNode } from "./types.js";
+type ComponentProps = Record<string, unknown> & {
+    children?: MusicNode | MusicNode[];
+};
+export declare function jsx(type: string | ((props: ComponentProps) => MusicNode), props: ComponentProps | null, key?: string): MusicNode;
+export declare function jsxs(type: string | ((props: ComponentProps) => MusicNode), props: ComponentProps | null, key?: string): MusicNode;
+export declare function Fragment(props: {
+    children?: MusicNode | MusicNode[];
+}): MusicNode[];
+export declare function collectChildren(children: MusicNode | MusicNode[] | undefined): MusicNode[];
+export {};

package/dist/jsx-runtime.js

@@ -0,0 +1,20 @@
+export function jsx(type, props, key) {
+    if (typeof type === "function") {
+        return type({ ...props, key });
+    }
+    throw new Error(`Unknown element: ${String(type)}`);
+}
+export function jsxs(type, props, key) {
+    return jsx(type, props, key);
+}
+export function Fragment(props) {
+    return normalizeChildren(props.children);
+}
+function normalizeChildren(children) {
+    if (children === undefined)
+        return [];
+    return Array.isArray(children) ? children : [children];
+}
+export function collectChildren(children) {
+    return normalizeChildren(children);
+}

package/dist/key-signature.d.ts

@@ -0,0 +1 @@
+export declare function keySignatureFifths(key: string): number;

package/dist/key-signature.js

@@ -0,0 +1,39 @@
+const KEY_FIFTHS = {
+    Cb: -7,
+    Gb: -6,
+    Db: -5,
+    Ab: -4,
+    Eb: -3,
+    Bb: -2,
+    F: -1,
+    C: 0,
+    G: 1,
+    D: 2,
+    A: 3,
+    E: 4,
+    B: 5,
+    "F#": 6,
+    "C#": 7,
+    Am: 0,
+    Em: 1,
+    Bm: 2,
+    "F#m": 3,
+    "C#m": 4,
+    "G#m": 5,
+    "D#m": 6,
+    "A#m": 7,
+    Dm: -1,
+    Gm: -2,
+    Cm: -3,
+    Fm: -4,
+    Bbm: -5,
+    Ebm: -6,
+    Abm: -7,
+};
+export function keySignatureFifths(key) {
+    const fifths = KEY_FIFTHS[key];
+    if (fifths === undefined) {
+        throw new Error(`Unsupported key signature: ${key}`);
+    }
+    return fifths;
+}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+export type TimeSignature = `${number}/${number}`;
+export type SongNode = {
+    type: "song";
+    tempo: number;
+    key: string;
+    time: TimeSignature;
+    title?: string;
+    children: MusicNode[];
+};
+export type LoopNode = {
+    type: "loop";
+    times: number;
+    children: MusicNode[];
+};
+export type SectionNode = {
+    type: "section";
+    name: string;
+    children: MusicNode[];
+};
+export type ChordBarNode = {
+    type: "chordBar";
+    chords: string[];
+};
+export type CommentNode = {
+    type: "comment";
+    text: string;
+};
+export type WordsNode = {
+    type: "words";
+    text: string;
+};
+export type MusicNode = SongNode | LoopNode | SectionNode | ChordBarNode | CommentNode | WordsNode;
+export type ParsedChord = {
+    symbol: string;
+    rootStep: string;
+    rootAlter: number;
+    kind: string;
+    kindText: string;
+    bassStep?: string;
+    bassAlter?: number;
+};
+export type FlatMeasure = {
+    chords: ParsedChord[];
+    section?: string;
+    comment?: string;
+    words?: string;
+};
+export type SongSettings = {
+    tempo: number;
+    key: string;
+    beatsPerMeasure: number;
+    beatType: number;
+    title?: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "music-jsx-compiler",
+  "version": "0.1.0",
+  "description": "JSX-like component framework for building MusicXML",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "example": "tsx --tsconfig tsconfig.examples.json examples/example.tsx",
+    "check": "tsc --noEmit && tsx src/self-check.ts && npm run example"
+  },
+  "keywords": [
+    "musicxml",
+    "jsx",
+    "music",
+    "chords",
+    "compiler",
+    "llm"
+  ],
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}