chord-synth 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,174 @@
+# chord-synth
+
+Generate chord progression WAV files. Zero dependencies. Node.js only.
+
+28 named presets, 22 arpeggio patterns, 7 instruments, slash chords (`Am/E`), transposition, pad/bass/drum tracks, reverb.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g chord-synth
+
+# Generate a WAV file
+chord-synth --preset "C G Am F" --bpm 120 --output pop.wav
+
+# Custom jazz with slash chords
+chord-synth --preset "Dm9 | G7/B | Cmaj7 | Am7/E" --instrument piano --drums bossanova --output jazz.wav
+
+# Named preset transposed to key of G
+chord-synth --preset "I-V-vi-IV (Pop)" --transpose 7 --output pop_in_G.wav
+
+# Batch render from JSON file
+chord-synth --batch render_jobs.json --output ./wavs/
+```
+
+## Use as MCP Server
+
+Exposes `generate_wav` and `list_options` tools to any MCP-compatible agent (Claude Desktop, Claude Code, Cursor, Windsurf, etc).
+
+**Claude Desktop** — add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "chord-synth": {
+      "command": "node",
+      "args": ["/path/to/chord-synth/mcp-server.js"]
+    }
+  }
+}
+```
+
+**Claude Code:**
+```bash
+claude mcp add chord-synth -- node /path/to/chord-synth/mcp-server.js
+```
+
+Then ask Claude: *"Generate a sad violin arpeggio over Am F C G at 80 BPM"* — it will call `generate_wav` directly.
+
+## Use as Node.js Module
+
+```javascript
+const { renderJob, PRESETS, SCHEMA } = require('chord-synth');
+const fs = require('fs');
+
+// Render a WAV buffer
+const wav = renderJob({
+  preset: "C G Am/E F",
+  bpm: 120,
+  instrument: "piano",
+  pattern: 1,        // Up
+  enablePad: true,
+  drumPattern: "poprock"
+});
+
+fs.writeFileSync('output.wav', wav);
+```
+
+## Agent Interface
+
+Agents should call `chord-synth --schema` to get the full JSON tool specification:
+
+```bash
+chord-synth --schema
+```
+
+Returns:
+```json
+{
+  "tool": "chord-synth",
+  "description": "Generate chord progression WAV files...",
+  "input_schema": {
+    "type": "object",
+    "required": ["preset"],
+    "properties": {
+      "preset": { "type": "string", "description": "Named preset or custom chords..." },
+      "bpm": { "type": "integer", "default": 120 },
+      "instrument": { "type": "string", "enum": ["piano","guitar","violin",...] },
+      ...
+    }
+  },
+  "examples": [...]
+}
+```
+
+List all available options:
+```bash
+chord-synth --list
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `preset` | string | *required* | Named preset (`"I-V-vi-IV (Pop)"`) or custom chords (`"C G Am/E F"`) |
+| `bpm` | int | 120 | Tempo |
+| `transpose` | int | 0 | Semitones (-11 to +11) |
+| `pattern` | int | 1 | Arp pattern index (see below) |
+| `rate` | string | `"1/8"` | Note rate: `1/1` `1/2` `1/4` `1/8` `1/16` `1/32` (add T for triplet) |
+| `instrument` | string | `"piano"` | `piano` `guitar` `violin` `flute` `clarinet` `cello` `bass` |
+| `octaveRange` | int | 1 | 1-4 octave span |
+| `baseOctave` | int | 3 | Starting MIDI octave |
+| `velocity` | int | 90 | MIDI velocity 1-127 |
+| `swing` | float | 0.5 | 0.5=straight, 0.66=medium, 0.75=heavy |
+| `loops` | int | 2 | Progression repetitions |
+| `enablePad` | bool | true | Sustained pad chord track |
+| `padOctave` | int | 4 | Pad voicing octave |
+| `padVolume` | float | 0.12 | Pad volume (0.0-0.3) |
+| `enableBass` | bool | true | Auto bass (slash chords set bass note) |
+| `enableDrums` | bool | true | Drum track |
+| `drumPattern` | string | `"poprock"` | See drum patterns below |
+| `reverbMix` | float | 0.18 | Reverb amount (0.0-0.5) |
+
+## Named Presets
+
+| Category | Presets |
+|----------|---------|
+| Pop/Rock | `I-V-vi-IV (Pop)`, `I-vi-IV-V (50s)`, `vi-IV-I-V (Sad)`, `I-IV-V-IV (Rock)`, `I-V-vi-iii-IV (Canon)` |
+| Jazz | `ii-V-I (Jazz)`, `I-vi-ii-V (Jazz Turnaround)`, `iii-vi-ii-V (Coltrane)`, `Autumn Leaves`, `So What`, `Steely Dan` |
+| Neo-Soul/R&B | `Neo-Soul I`, `Neo-Soul II`, `R&B Smooth` |
+| Blues | `12-Bar Blues`, `Minor Blues` |
+| Latin | `Bossa Nova`, `Girl from Ipanema`, `Andalusian Cadence`, `Royal Road (JP)` |
+| Modal/Ambient | `Dorian Vamp`, `Lydian Float`, `Ambient Pads` |
+| EDM | `EDM Anthem`, `Trance`, `House` |
+| Classic | `Pachelbel Canon`, `Gospel` |
+
+Or use any custom chord string: `"Fmaj7 Em7 Dm9 Cmaj7"`, `"Am | Dm/F | E7 | Am"`, etc.
+
+## Arp Patterns
+
+| Index | Name | Index | Name |
+|-------|------|-------|------|
+| 0 | Chord (Block) | 11 | Pinky-Thumb |
+| 1 | Up | 12 | Thumb-Pinky |
+| 2 | Down | 13 | 1-3-5-3 |
+| 3 | Up-Down | 14 | 1-5-3-5 |
+| 4 | Down-Up | 15 | 1-5-8-5 |
+| 5 | Up-Down (No Repeat) | 16 | 1-3-5-8-5-3 |
+| 6 | Down-Up (No Repeat) | 17 | Alberti Bass |
+| 7 | Random | 18 | Stride |
+| 8 | Random Walk | 19 | Broken 3rds |
+| 9 | Outside-In | 20 | Pedal Tone |
+| 10 | Inside-Out | 21 | Alternating Bass |
+
+## Drum Patterns
+
+`8beat` `16beat` `poprock` `acousticpop` `bossanova` `swing` `funk` `rnb` `waltz` `arpeggio` `none`
+
+## Chord Notation
+
+Roots: `C C# Db D D# Eb E F F# Gb G G# Ab A A# Bb B`
+
+Qualities: `(major)` `m` `7` `maj7` `m7` `dim` `aug` `sus2` `sus4` `9` `m9` `maj9` `11` `m11` `13` `6` `m6` `dim7` `m7b5` `add9` `5` `power`
+
+Slash chords: `Am/E` (Am chord, E bass note), `C/G`, `Dm7/A`
+
+Separator: spaces or `|` both work. `C G Am F` = `C | G | Am | F`
+
+## Output
+
+WAV PCM 16-bit mono 44100 Hz. Compatible with all DAWs, audio players, and audio processing tools.
+
+## License
+
+MIT

package/bin/chord-synth.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * chord-synth CLI
+ * 
+ * Self-describing command-line interface for autonomous agents and humans.
+ * Run with --schema to get full JSON parameter spec.
+ * 
+ * Usage:
+ *   chord-synth --schema                          # JSON schema (agent-readable)
+ *   chord-synth --list                             # all options as JSON
+ *   chord-synth --preset "C G Am/E F" --bpm 120    # render single file
+ *   chord-synth --json '{"preset":"Am F C G"}'     # render from inline JSON
+ *   chord-synth --batch render_jobs.json            # batch render from file
+ *   chord-synth --batch render_jobs.json --dry-run  # validate without rendering
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const engine = require('../lib/synth-engine');
+
+const args = process.argv.slice(2);
+
+// ── Subcommand: "mcp" launches the MCP server ──
+if (args[0] === 'mcp') {
+  require('../mcp-server.js');
+} else {
+
+function flag(name) { return args.includes('--' + name); }
+function flagVal(name) {
+  const i = args.indexOf('--' + name);
+  return i >= 0 && i + 1 < args.length ? args[i + 1] : null;
+}
+function flagNum(name, def) { const v = flagVal(name); return v !== null ? Number(v) : def; }
+
+// ── --schema: machine-readable parameter specification ──
+if (flag('schema')) {
+  const spec = {
+    tool: "chord-synth",
+    version: require('../package.json').version,
+    description: "Generate chord progression WAV files. Renders arpeggio patterns with configurable instruments, drums, pads, and effects. Supports 28 named presets, 22 arp patterns, 7 instruments, slash chords (Am/E), and transposition.",
+    input_schema: engine.SCHEMA,
+    output: { type: "file", format: "WAV PCM 16-bit mono 44100Hz" },
+    examples: [
+      { description: "Pop piano arpeggio", args: { preset: "I-V-vi-IV (Pop)", bpm: 120, instrument: "piano", pattern: 1 } },
+      { description: "Custom jazz with slash chords", args: { preset: "Dm9 | G7/B | Cmaj7 | Am7/E", bpm: 92, instrument: "piano", pattern: 17, swing: 0.62 } },
+      { description: "Ambient pad wash, no drums", args: { preset: "Cmaj9 Am9 Fmaj9 Gsus4", bpm: 55, enableDrums: false, padVolume: 0.24, reverbMix: 0.35 } },
+      { description: "Transposed to key of G", args: { preset: "I-V-vi-IV (Pop)", transpose: 7, bpm: 120 } }
+    ]
+  };
+  process.stdout.write(JSON.stringify(spec, null, 2) + '\n');
+  process.exit(0);
+}
+
+// ── --list: all available options as JSON ──
+if (flag('list')) {
+  process.stdout.write(JSON.stringify({
+    presets: engine.PRESETS,
+    patterns: engine.PATTERNS,
+    instruments: engine.INSTRUMENTS,
+    drums: engine.DRUMS,
+    rates: engine.RATES
+  }, null, 2) + '\n');
+  process.exit(0);
+}
+
+// ── --help: human-readable ──
+if (flag('help') || flag('h') || args.length === 0) {
+  console.log(`
+chord-synth — Generate chord progression WAV files
+
+AGENT COMMANDS (machine-readable output):
+  --schema              Full JSON tool specification with parameter schema
+  --list                All available presets, patterns, instruments, drums as JSON
+  mcp                   Launch as MCP server (stdio JSON-RPC for Claude/Cursor/etc)
+
+RENDER COMMANDS:
+  --preset "chords"     Named preset or custom chords (required for single render)
+  --bpm N               Tempo (default: 120)
+  --instrument NAME     piano|guitar|violin|flute|clarinet|cello (default: piano)
+  --pattern N           Arp pattern 0-21 (default: 1=Up)
+  --rate RATE           1/8, 1/16, 1/4, etc (default: 1/8)
+  --transpose N         Semitones -11 to +11 (default: 0)
+  --drums PATTERN       poprock|swing|bossanova|funk|rnb|8beat|none (default: poprock)
+  --loops N             Repetitions (default: 2)
+  --output FILE         Output WAV path (default: ./output.wav)
+  --json '{"key":"val"}' Full job as inline JSON
+  --batch FILE          Batch render from JSON array file
+  --dry-run             Validate batch file without rendering
+
+QUICK EXAMPLES:
+  chord-synth --preset "C G Am F" --bpm 120 --output pop.wav
+  chord-synth --preset "ii-V-I (Jazz)" --instrument piano --drums swing --swing 0.62
+  chord-synth --json '{"preset":"Am F C/G G","bpm":100,"instrument":"violin"}'
+  chord-synth --batch render_jobs.json --output ./wavs/
+  chord-synth --schema | jq .input_schema    # agent: read parameter spec
+  chord-synth mcp                             # start MCP server on stdio
+`);
+  process.exit(0);
+}
+
+// ── --batch: batch render from JSON file ──
+const batchFile = flagVal('batch');
+if (batchFile) {
+  if (!fs.existsSync(batchFile)) { console.error(`File not found: ${batchFile}`); process.exit(1); }
+  const jobs = JSON.parse(fs.readFileSync(batchFile, 'utf8'));
+  const arr = Array.isArray(jobs) ? jobs : (jobs.RENDER_JOBS || jobs.jobs || [jobs]);
+  const outDir = flagVal('output') || (jobs.OUTPUT_DIR || './output');
+  const dryRun = flag('dry-run');
+
+  if (dryRun) {
+    console.log(JSON.stringify({ valid: true, jobs: arr.length, output_dir: outDir }));
+    process.exit(0);
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  console.error(`Rendering ${arr.length} jobs to ${outDir}...`);
+  const results = [];
+  for (let i = 0; i < arr.length; i++) {
+    const job = arr[i];
+    const filename = job.filename || `${String(i + 1).padStart(3, '0')}_output.wav`;
+    console.error(`[${i + 1}/${arr.length}] ${filename}`);
+    const wavData = engine.renderJob(job);
+    const outPath = path.join(outDir, filename);
+    fs.writeFileSync(outPath, wavData);
+    results.push({ filename, path: outPath, size: wavData.length });
+  }
+  // Output structured result to stdout (agent reads this)
+  process.stdout.write(JSON.stringify({ rendered: results.length, files: results }) + '\n');
+  process.exit(0);
+}
+
+// ── --json: inline JSON render ──
+const jsonStr = flagVal('json');
+if (jsonStr) {
+  const job = JSON.parse(jsonStr);
+  const outFile = flagVal('output') || 'output.wav';
+  fs.mkdirSync(path.dirname(path.resolve(outFile)), { recursive: true });
+  const wavData = engine.renderJob(job);
+  fs.writeFileSync(outFile, wavData);
+  process.stdout.write(JSON.stringify({ file: outFile, size: wavData.length }) + '\n');
+  process.exit(0);
+}
+
+// ── --preset: single render from flags ──
+const preset = flagVal('preset');
+if (preset) {
+  const job = {
+    preset,
+    bpm:            flagNum('bpm', 120),
+    transpose:      flagNum('transpose', 0),
+    pattern:        flagNum('pattern', 1),
+    rate:           flagVal('rate') || '1/8',
+    instrument:     flagVal('instrument') || 'piano',
+    octaveRange:    flagNum('octave-range', 1),
+    baseOctave:     flagNum('base-octave', 3),
+    gatePercent:    flagNum('gate', 0.9),
+    velocity:       flagNum('velocity', 90),
+    velRandom:      flagNum('vel-random', 5),
+    accentEvery:    flagNum('accent-every', 4),
+    accentAmount:   flagNum('accent-amount', 20),
+    firstBeatAccent: !flag('no-first-accent'),
+    swing:          flagNum('swing', 0.5),
+    loops:          flagNum('loops', 2),
+    enablePad:      !flag('no-pad'),
+    padOctave:      flagNum('pad-octave', 4),
+    padVolume:      flagNum('pad-volume', 0.12),
+    enableBass:     !flag('no-bass'),
+    enableDrums:    !flag('no-drums'),
+    drumPattern:    flagVal('drums') || 'poprock',
+    reverbMix:      flagNum('reverb', 0.18),
+    masterVolume:   flagNum('volume', 0.85),
+    beatsPerChord:  flagNum('beats-per-chord', undefined),
+  };
+
+  const outFile = flagVal('output') || 'output.wav';
+  fs.mkdirSync(path.dirname(path.resolve(outFile)), { recursive: true });
+  const wavData = engine.renderJob(job);
+  fs.writeFileSync(outFile, wavData);
+  process.stdout.write(JSON.stringify({ file: outFile, size: wavData.length, preset, bpm: job.bpm }) + '\n');
+  process.exit(0);
+}
+
+console.error('No action specified. Run with --help or --schema.');
+process.exit(1);
+
+} // end else (not mcp)