scribbletune 5.4.0 → 5.5.1

package/README.md

@@ -1,41 +1,364 @@
-## <img width=2% src="https://scribbletune.com/images/scribbletune-logo.png"> SCRIBBLETUNE
+<p align="center">
+  <img width="64" src="https://scribbletune.com/images/scribbletune-logo.png" alt="Scribbletune">
+</p>
 
-[![Build Status](https://travis-ci.com/scribbletune/scribbletune.svg?branch=master)](http://travis-ci.com/scribbletune/scribbletune)
-[![Try scribbletune on RunKit](https://badge.runkitcdn.com/scribbletune.svg)](https://npm.runkit.com/scribbletune)
+<h1 align="center">Scribbletune</h1>
 
-Use simple **JavaScript** `Strings` and `Arrays` to generate rhythms and musical patterns. Directly use the names of scales or chords in your code to get arrays which you can mash up using Array methods in ways you hadn't imagined before! Create clips of musical ideas and **export MIDI files** which you can import in _Ableton Live, Reason, GarageBand_ or any music creation software that accepts MIDI files.
+<p align="center">
+  Create music with JavaScript. Use simple strings and arrays to craft rhythms, melodies, and chord progressions — then export MIDI files or play them live in the browser with <a href="https://tonejs.github.io/">Tone.js</a>.
+</p>
 
-### Install
+<p align="center">
+  <a href="https://www.npmjs.com/package/scribbletune"><img src="https://img.shields.io/npm/v/scribbletune.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/scribbletune"><img src="https://img.shields.io/npm/l/scribbletune.svg" alt="license"></a>
+</p>
+
+---
+
+## Install
+
+```bash
+npm install scribbletune
+```
+
+## Quick start
+
+### CLI
+
+The package now ships a CLI binary: `scribbletune`.
+
+Run modes:
 
 ```bash
+# Global install
+npm install -g scribbletune
+scribbletune --help
+
+# Local/project install
 npm install scribbletune
+npx scribbletune --help
+```
+
+Quick command examples:
+
+```bash
+# Use built file directly from repo (before publish)
+node dist/cli.cjs --help
+
+# Use local package binary
+npx scribbletune --help
+
+# If installed globally
+scribbletune --help
+```
+
+#### Command format
+
+```bash
+scribbletune --riff <root> <mode> <pattern> [octaveShift] [motif] [options]
+scribbletune --chord <root> <mode> <progression|random> <pattern> [subdiv] [options]
+scribbletune --arp <root> <mode> <progression|random> <pattern> [subdiv] [options]
+```
+
+Progression input rules for `--chord` and `--arp`:
+
+```bash
+1645            # degree digits
+"I IV vi V"     # roman numerals (space separated)
+I,IV,vi,V       # roman numerals (comma separated)
+random          # generated progression
+CM-FM-Am-GM     # explicit chord names
+```
+
+Notes:
+- Hyphenated romans like `I-IV-vi-V` are not supported currently.
+- For explicit chords (`CM-FM-Am-GM`), `root` and `mode` are currently ignored.
+
+Common options:
+
+```bash
+--outfile <file.mid>    # default: music.mid
+--bpm <number>
+--subdiv <4n|8n|1m...>
+--sizzle [sin|cos|rampUp|rampDown] [reps]
+--sizzle-reps <number>
+--amp <0-127>
+--accent <x--x...>
+--accent-low <0-127>
+--fit-pattern         # explicit enable (already enabled by default)
+--no-fit-pattern      # disable automatic pattern fitting
+```
+
+Note: if your pattern uses `[` and `]` (for subdivisions), quote it in shell:
+
+```bash
+scribbletune --arp C3 major 1 'x-x[xx]-x-[xx]' 16n
+```
+
+Pattern helpers:
+
+```bash
+x.repeat(4)       # -> xxxx
+'x-x[xx]'.repeat(2)
+2(x-x[xx])        # prefix repeat shorthand
+(x-x[xx])2        # suffix repeat shorthand
+```
+
+#### `--riff` examples
+
+```bash
+# Basic riff from scale
+scribbletune --riff C3 phrygian x-xRx_RR --outfile riff.mid
+
+# With octave shift and motif
+scribbletune --riff C3 phrygian x-xRx_RR 0 AABC --sizzle sin 2 --outfile riff-aabc.mid
+
+# Pattern with subdivisions (quote [] in shell)
+scribbletune --riff C3 phrygian 'x-x[xx]-x-[xx]' 0 AABC --outfile riff-subdiv.mid
+```
+
+#### `--chord` examples
+
+```bash
+# Degree digits (resolved against root/mode)
+scribbletune --chord C3 major 1645 xxxx 1m --sizzle cos 1 --outfile chords-1645.mid
+
+# Roman numerals (space/comma separated)
+scribbletune --chord C3 major "I IV vi V" xxxx 1m --outfile chords-roman.mid
+
+# Random progression
+scribbletune --chord C3 major random xxxx 1m --outfile chords-random.mid
+
+# Explicit chord names (root/mode currently ignored for this style)
+scribbletune --chord C3 major CM-FM-Am-GM xxxx 1m --outfile chords-explicit.mid
+
+# Subdivisions in pattern
+scribbletune --chord C3 major I,IV,vi,V 'x-x[xx]-x-[xx]' 8n --outfile chords-subdiv.mid
+```
+
+#### `--arp` examples
+
+```bash
+# Arp from degree progression
+scribbletune --arp C3 major 1736 xxxx 1m --sizzle cos 4 --outfile arp-1736.mid
+
+# Single degree "1" means tonic chord in the chosen key/mode
+scribbletune --arp C3 major 1 xxxx 4n --outfile arp-degree-1.mid
+
+# Arp from explicit chords
+scribbletune --arp C3 major CM-FM-Am-GM xxxx 1m --count 4 --order 1234 --outfile arp-explicit.mid
+
+# Custom note order inside each arpeggiated chord (one-based)
+scribbletune --arp C3 major 1 xxxx 4n --order 2143 --outfile arp-order-2143.mid
+
+# Same custom order using local dist build
+node dist/cli.cjs --arp C3 major 1 xxxx 4n --order 2143 --outfile arp-order-local.mid
+
+# Auto-fit is default (single x expands to full generated arp length)
+scribbletune --arp C3 major 1736 x 4n --outfile arp-fit-default.mid
+
+# Disable auto-fit if you want a short clip
+scribbletune --arp C3 major 1736 x 4n --no-fit-pattern --outfile arp-no-fit.mid
+```
+
+`--order` behavior:
+- One-based order is supported (`1234`, `2143`) and is recommended.
+- Zero-based order is also accepted for backward compatibility (`0123`, `1032`).
+
+Run `scribbletune --help` to see the latest CLI usage text.
+
+### Generate a MIDI file (Node.js)
+
+```js
+import { scale, clip, midi } from 'scribbletune';
+
+const notes = scale('C4 major');
+const c = clip({ notes, pattern: 'x'.repeat(8) });
+
+midi(c, 'c-major.mid');
 ```
 
-### Use it to create a MIDI clip by running a JS file from your terminal using node.js
-```javascript
-const scribble = require('scribbletune');
-const clip = scribble.clip({
-    notes: scribble.scale('C4 major'),
-    pattern: 'x'.repeat(7) + '_'
+Run it with `node` and open the `.mid` file in Ableton Live, GarageBand, Logic, or any DAW.
+
+### Play in the browser (with Tone.js)
+
+Scribbletune's browser entry point adds `Session`, `Channel`, and live `clip()` support on top of [Tone.js](https://tonejs.github.io/).
+
+```js
+import { Session } from 'scribbletune/browser';
+
+const session = new Session();
+const channel = session.createChannel({
+  instrument: 'PolySynth',
+  clips: [
+    { pattern: 'x-x-', notes: 'C4 E4 G4' },
+    { pattern: '[-xx]', notes: 'C4 D#4' },
+  ],
 });
 
-scribble.midi(clip, 'c-major.mid');
+await Tone.start();
+Tone.Transport.start();
+channel.startClip(0);
 ```
 
+### Standalone sample clip (no Session/Channel needed)
 
-You can use Scribbletune even **in the browser** with Tone.js!. There are a couple of ways to do this. A quick and dirty way is to make sure to pull in [Tone.js](https://cdnjs.com/libraries/tone) followed by the [latest browser version of Scribbletune](https://cdnjs.com/libraries/scribbletune).
+```js
+import { clip } from 'scribbletune/browser';
 
-```html
-<script src="https://cdnjs.cloudflare.com/ajax/libs/tone/<LATEST-VERSION-FROM-CDNJS>/Tone.min.js"></script>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/scribbletune/<LATEST-VERSION-FROM-CDNJS>/scribbletune.js"></script>
+await Tone.start();
+Tone.Transport.start();
+
+const kick = clip({
+  sample: 'https://scribbletune.com/sounds/kick.wav',
+  pattern: 'x-x-',
+});
+kick.start();
 ```
 
-This will expose a global object called `scribble` which you can directly use to run the methods from Scribbletune in conjunction with Tone.js
+## Core concepts
+
+### Pattern language
+
+Scribbletune uses a simple string notation to describe rhythms:
+
+| Char | Meaning |
+|------|---------|
+| `x` | Note on |
+| `-` | Note off (rest) |
+| `_` | Sustain previous note |
+| `R` | Random note (from `randomNotes` pool) |
+| `[]` | Subdivide (e.g. `[xx]` = two notes in one beat) |
+
+```js
+'x---x---x-x-x---'   // basic kick pattern
+'[xx][xx]x-x-'        // hihat with subdivisions
+'x___'                 // one long sustained note
+```
+
+### Scales and chords
+
+Powered by [harmonics](https://github.com/scribbletune/harmonics):
+
+```js
+import { scale, chord, scales, chords } from 'scribbletune';
+
+scale('C4 major');       // ['C4', 'D4', 'E4', 'F4', 'G4', 'A4', 'B4']
+chord('CM');             // ['C4', 'E4', 'G4']
+scales();                // list all available scale names
+chords();                // list all available chord names
+```
+
+### Arpeggios
+
+```js
+import { arp } from 'scribbletune';
+
+arp({ chords: 'CM FM', count: 4, order: '0123' });
+// ['C4', 'E4', 'G4', 'C5', 'F4', 'A4', 'C5', 'F5']
+```
+
+### Chord progressions
+
+```js
+import { progression, getChordsByProgression } from 'scribbletune';
+
+progression('M', 4);  // e.g. ['I', 'ii', 'V', 'IV']
 
-The recommended way for the browser, however, is to import it like this
-```javascript
-const scribble = require('scribbletune/browser');
+getChordsByProgression('C4 major', 'I IV V IV');
+// 'CM_4 FM_4 GM_4 FM_4'
 ```
-This will provide the same API but augment it a bit to support browser based functionality.
 
-Visit [scribbletune.com](https://scribbletune.com) for documentation, tutorials and examples! Listen to music generated with Scribbletune on [Soundcloud](https://soundcloud.com/scribbletune).
+## Browser API
+
+The browser entry point (`scribbletune/browser`) provides everything above plus:
+
+### Session and Channel
+
+```js
+import { Session } from 'scribbletune/browser';
+
+const session = new Session();
+const drums = session.createChannel({
+  sample: 'https://scribbletune.com/sounds/kick.wav',
+  clips: [
+    { pattern: 'x---x---' },
+    { pattern: 'x-x-x-x-' },
+  ],
+});
+
+const synth = session.createChannel({
+  instrument: 'PolySynth',
+  clips: [
+    { pattern: 'x-x-', notes: 'C4 E4 G4' },
+  ],
+});
+
+await Tone.start();
+Tone.Transport.start();
+
+// Start clips independently
+drums.startClip(0);
+synth.startClip(0);
+
+// Switch patterns on the fly
+drums.startClip(1);
+
+// Or start a row across all channels
+session.startRow(0);
+```
+
+### Channel options
+
+Channels accept various sound sources:
+
+```js
+// Built-in Tone.js synth (by name)
+{ instrument: 'PolySynth' }
+
+// Pre-built Tone.js instrument
+{ instrument: new Tone.FMSynth() }
+
+// Audio sample URL
+{ sample: 'https://example.com/kick.wav' }
+
+// Multi-sample instrument
+{ samples: { C3: 'piano-c3.wav', D3: 'piano-d3.wav' } }
+
+// With effects
+{ instrument: 'PolySynth', effects: ['Chorus', 'Reverb'] }
+```
+
+## API reference
+
+| Export | Description |
+|--------|-------------|
+| `clip(params)` | Create a clip — returns note objects (Node.js) or a Tone.Sequence (browser) |
+| `midi(clip, filename?)` | Export a clip to a MIDI file |
+| `scale(name)` | Get notes of a scale, e.g. `'C4 minor'` |
+| `chord(name)` | Get notes of a chord, e.g. `'CM'` |
+| `scales()` | List all available scale names |
+| `chords()` | List all available chord names |
+| `arp(params)` | Generate arpeggiated note sequences |
+| `progression(type, count)` | Generate a chord progression (`'M'` or `'m'`) |
+| `getChordsByProgression(scale, degrees)` | Convert Roman numeral degrees to chord names |
+| `getChordDegrees(mode)` | Get Roman numeral degrees for a mode |
+| `Session` | _(browser only)_ Manage multiple channels and coordinate playback |
+
+## Development
+
+```bash
+npm install       # install dependencies
+npm test          # run tests
+npm run build     # build with tsup
+npm run lint      # check with biome
+npm run dev       # build in watch mode
+```
+
+## License
+
+MIT
+
+---
+
+[scribbletune.com](https://scribbletune.com) | [Soundcloud](https://soundcloud.com/scribbletune)

package/dist/cli.cjs

@@ -0,0 +1,884 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+var import_harmonics4 = require("harmonics");
+
+// src/arp.ts
+var import_harmonics2 = require("harmonics");
+
+// src/utils.ts
+var import_harmonics = require("harmonics");
+var isNote = (str) => /^[a-gA-G](?:#|b)?\d$/.test(str);
+var expandStr = (str) => {
+  str = JSON.stringify(str.split(""));
+  str = str.replace(/,"\[",/g, ", [");
+  str = str.replace(/"\[",/g, "[");
+  str = str.replace(/,"\]"/g, "]");
+  return JSON.parse(str);
+};
+var shuffle = (arr, fullShuffle = true) => {
+  const lastIndex = arr.length - 1;
+  arr.forEach((el, idx) => {
+    if (idx >= lastIndex) {
+      return;
+    }
+    const rnd = fullShuffle ? (
+      // Pick random number from idx+1 to lastIndex (Modified algorithm, (N-1)! combinations)
+      // Math.random -> [0, 1) -> [0, lastIndex-idx ) --floor-> [0, lastIndex-idx-1]
+      // rnd = [0, lastIndex-idx-1] + 1 + idx = [1 + idx, lastIndex]
+      // (Original algorithm would pick rnd = [idx, lastIndex], thus any element could arrive back into its slot)
+      Math.floor(Math.random() * (lastIndex - idx)) + 1 + idx
+    ) : (
+      // Pick random number from idx to lastIndex (Unmodified Richard Durstenfeld, N! combinations)
+      Math.floor(Math.random() * (lastIndex + 1 - idx)) + idx
+    );
+    arr[idx] = arr[rnd];
+    arr[rnd] = el;
+  });
+  return arr;
+};
+var pickOne = (arr) => arr[Math.floor(Math.random() * arr.length)];
+var dice = () => !!Math.round(Math.random());
+var errorHasMessage = (x) => {
+  return typeof x === "object" && x !== null && "message" in x && typeof x.message === "string";
+};
+var convertChordToNotes = (el) => {
+  let c1;
+  let c2;
+  let e1;
+  let e2;
+  try {
+    c1 = (0, import_harmonics.inlineChord)(el);
+  } catch (e) {
+    e1 = e;
+  }
+  try {
+    c2 = (0, import_harmonics.chord)(el.replace(/_/g, " "));
+  } catch (e) {
+    e2 = e;
+  }
+  if (!e1 && !e2) {
+    if (c1.toString() !== c2.toString()) {
+      throw new Error(`Chord ${el} cannot decode, guessing ${c1} or ${c2}`);
+    }
+    return c1;
+  }
+  if (!e1) {
+    return c1;
+  }
+  if (!e2) {
+    return c2;
+  }
+  return (0, import_harmonics.chord)(el);
+};
+var convertChordsToNotes = (el) => {
+  if (typeof el === "string" && isNote(el)) {
+    return [el];
+  }
+  if (Array.isArray(el)) {
+    el.forEach((n) => {
+      if (Array.isArray(n)) {
+        n.forEach((n1) => {
+          if (typeof n1 !== "string" || !isNote(n1)) {
+            throw new TypeError("array of arrays must comprise valid notes");
+          }
+        });
+      } else if (typeof n !== "string" || !isNote(n)) {
+        throw new TypeError("array must comprise valid notes");
+      }
+    });
+    return el;
+  }
+  if (!Array.isArray(el)) {
+    const c = convertChordToNotes(el);
+    if (c?.length) {
+      return c;
+    }
+  }
+  throw new Error(`Chord ${el} not found`);
+};
+var randomInt = (num = 1) => Math.round(Math.random() * num);
+
+// src/arp.ts
+var DEFAULT_OCTAVE = 4;
+var fillArr = (arr, len) => {
+  const bumpOctave = (el) => {
+    if (!el) {
+      throw new Error("Empty element");
+    }
+    const note = el.replace(/\d/, "");
+    const oct = el.replace(/\D/g, "") || DEFAULT_OCTAVE;
+    if (!note) {
+      throw new Error("Incorrect note");
+    }
+    return note + (+oct + 1);
+  };
+  const arr1 = arr.map(bumpOctave);
+  const arr2 = arr1.map(bumpOctave);
+  const finalArr = [...arr, ...arr1, ...arr2];
+  return finalArr.slice(0, len);
+};
+var arp = (chordsOrParams) => {
+  let finalArr = [];
+  const params = {
+    count: 4,
+    order: "0123",
+    chords: ""
+  };
+  if (typeof chordsOrParams === "string") {
+    params.chords = chordsOrParams;
+  } else {
+    if (chordsOrParams.order?.match(/\D/g)) {
+      throw new TypeError("Invalid value for order");
+    }
+    if (chordsOrParams.count > 8 || chordsOrParams.count < 2) {
+      throw new TypeError("Invalid value for count");
+    }
+    if (chordsOrParams.count && !chordsOrParams.order) {
+      params.order = Array.from(Array(chordsOrParams.count).keys()).join("");
+    }
+    Object.assign(params, chordsOrParams);
+  }
+  if (typeof params.chords === "string") {
+    const chordsArr = params.chords.split(" ");
+    chordsArr.forEach((c, i) => {
+      try {
+        const filledArr = fillArr((0, import_harmonics2.inlineChord)(c), params.count);
+        const reorderedArr = params.order.split("").map((idx) => filledArr[Number(idx)]);
+        finalArr = [...finalArr, ...reorderedArr];
+      } catch (_e) {
+        throw new Error(
+          `Cannot decode chord ${i + 1} "${c}" in given "${params.chords}"`
+        );
+      }
+    });
+  } else if (Array.isArray(params.chords)) {
+    params.chords.forEach((c, i) => {
+      try {
+        const filledArr = fillArr(c, params.count);
+        const reorderedArr = params.order.split("").map((idx) => filledArr[Number(idx)]);
+        finalArr = [...finalArr, ...reorderedArr];
+      } catch (e) {
+        throw new Error(
+          `${errorHasMessage(e) ? e.message : e} in chord ${i + 1} "${c}"`
+        );
+      }
+    });
+  } else {
+    throw new TypeError("Invalid value for chords");
+  }
+  return finalArr;
+};
+
+// src/clip-utils.ts
+var defaultParams = {
+  notes: ["C4"],
+  pattern: "x",
+  shuffle: false,
+  sizzle: false,
+  sizzleReps: 1,
+  arpegiate: false,
+  subdiv: "4n",
+  amp: 100,
+  accentLow: 70,
+  randomNotes: null,
+  offlineRendering: false
+};
+var validatePattern = (pattern) => {
+  if (/[^x\-_[\]R]/.test(pattern)) {
+    throw new TypeError(
+      `pattern can only comprise x - _ [ ] R, found ${pattern}`
+    );
+  }
+};
+var preprocessClipParams = (params, extraDefaults) => {
+  params = { ...defaultParams, ...extraDefaults, ...params || {} };
+  if (typeof params.notes === "string") {
+    params.notes = params.notes.replace(/\s{2,}/g, " ").split(" ");
+  }
+  params.notes = params.notes ? params.notes.map(convertChordsToNotes) : [];
+  validatePattern(params.pattern);
+  if (params.shuffle) {
+    params.notes = shuffle(params.notes);
+  }
+  if (params.randomNotes && typeof params.randomNotes === "string") {
+    params.randomNotes = params.randomNotes.replace(/\s{2,}/g, " ").split(/\s/);
+  }
+  if (params.randomNotes) {
+    params.randomNotes = params.randomNotes.map(
+      convertChordsToNotes
+    );
+  }
+  return params;
+};
+
+// src/clip.ts
+var hdr = {
+  "1m": 2048,
+  "2m": 4096,
+  "3m": 6144,
+  "4m": 8192,
+  "1n": 512,
+  "2n": 256,
+  "4n": 128,
+  "8n": 64,
+  "16n": 32
+};
+var clip = (params) => {
+  params = preprocessClipParams(params);
+  const clipNotes = [];
+  let step = 0;
+  const recursivelyApplyPatternToNotes = (patternArr, length, parentNoteLength) => {
+    let totalLength = 0;
+    patternArr.forEach((char, idx) => {
+      if (typeof char === "string") {
+        let note = null;
+        if (char === "-") {
+        } else if (char === "R" && randomInt() && // Use 1/2 probability for R to pick from param.notes
+        params.randomNotes && params.randomNotes.length > 0) {
+          note = params.randomNotes[randomInt(params.randomNotes.length - 1)];
+        } else if (params.notes) {
+          note = params.notes[step];
+        }
+        if (char === "x" || char === "R") {
+          step++;
+        }
+        if (char === "x" || char === "-" || char === "R") {
+          clipNotes.push({
+            note,
+            length,
+            level: char === "R" && !params.randomNotes ? params.accentLow : params.amp
+          });
+          totalLength += length;
+        }
+        if (char === "_" && clipNotes.length) {
+          clipNotes[clipNotes.length - 1].length += length;
+          totalLength += length;
+        }
+        if (parentNoteLength && totalLength !== parentNoteLength && idx === patternArr.length - 1) {
+          const diff = Math.abs(
+            parentNoteLength - totalLength
+          );
+          const lastClipNote = clipNotes[clipNotes.length - 1];
+          if (lastClipNote.length > diff) {
+            lastClipNote.length = lastClipNote.length - diff;
+          } else {
+            lastClipNote.length = lastClipNote.length + diff;
+          }
+        }
+        if (step === params.notes?.length) {
+          step = 0;
+        }
+      }
+      if (Array.isArray(char)) {
+        let isTriplet = false;
+        if (char.length % 2 !== 0 || length % 2 !== 0) {
+          isTriplet = true;
+        }
+        recursivelyApplyPatternToNotes(
+          char,
+          Math.round(length / char.length),
+          isTriplet && length
+        );
+        totalLength += length;
+      }
+    });
+  };
+  recursivelyApplyPatternToNotes(
+    expandStr(params.pattern),
+    hdr[params.subdiv] || hdr["4n"],
+    false
+  );
+  if (params.sizzle) {
+    const volArr = [];
+    const style = params.sizzle === true ? "sin" : params.sizzle;
+    const beats = clipNotes.length;
+    const amp = params.amp;
+    const sizzleReps = params.sizzleReps;
+    const stepLevel = amp / (beats / sizzleReps);
+    if (style === "sin" || style === "cos") {
+      for (let i = 0; i < beats; i++) {
+        const level = Math[style](i * Math.PI / (beats / sizzleReps)) * amp;
+        volArr.push(Math.round(Math.abs(level)));
+      }
+    }
+    if (style === "rampUp") {
+      let level = 0;
+      for (let i = 0; i < beats; i++) {
+        if (i % (beats / sizzleReps) === 0) {
+          level = 0;
+        } else {
+          level = level + stepLevel;
+        }
+        volArr.push(Math.round(Math.abs(level)));
+      }
+    }
+    if (style === "rampDown") {
+      let level = amp;
+      for (let i = 0; i < beats; i++) {
+        if (i % (beats / sizzleReps) === 0) {
+          level = amp;
+        } else {
+          level = level - stepLevel;
+        }
+        volArr.push(Math.round(Math.abs(level)));
+      }
+    }
+    for (let i = 0; i < volArr.length; i++) {
+      clipNotes[i].level = volArr[i] ? volArr[i] : 1;
+    }
+  }
+  if (params.accent) {
+    if (/[^x-]/.test(params.accent)) {
+      throw new TypeError("Accent can only have x and - characters");
+    }
+    let a = 0;
+    for (const clipNote of clipNotes) {
+      let level = params.accent[a] === "x" ? params.amp : params.accentLow;
+      if (params.sizzle) {
+        level = (clipNote.level + level) / 2;
+      }
+      clipNote.level = Math.round(level);
+      a = a + 1;
+      if (a === params.accent.length) {
+        a = 0;
+      }
+    }
+  }
+  return clipNotes;
+};
+
+// src/midi.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_midi = require("@scribbletune/midi");
+var midi = (notes, fileName = "music.mid", bpm) => {
+  const file = createFileFromNotes(notes, bpm);
+  const bytes = file.toBytes();
+  if (fileName === null) {
+    return bytes;
+  }
+  if (!fileName.endsWith(".mid")) {
+    fileName = `${fileName}.mid`;
+  }
+  if (typeof window !== "undefined" && window.URL && typeof window.URL.createObjectURL === "function") {
+    return createDownloadLink(bytes, fileName);
+  }
+  import_node_fs.default.writeFileSync(fileName, bytes, "binary");
+  console.log(`MIDI file generated: ${fileName}.`);
+};
+var createDownloadLink = (b, fileName) => {
+  const bytes = new Uint8Array(b.length);
+  for (let i = 0; i < b.length; i++) {
+    const ascii = b.charCodeAt(i);
+    bytes[i] = ascii;
+  }
+  const blob = new Blob([bytes], { type: "audio/midi" });
+  const link = document.createElement("a");
+  link.href = typeof window !== "undefined" && typeof window.URL !== "undefined" && typeof window.URL.createObjectURL !== "undefined" && window.URL.createObjectURL(blob) || "";
+  link.download = fileName;
+  link.innerText = "Download MIDI file";
+  return link;
+};
+var createFileFromNotes = (notes, bpm) => {
+  const file = new import_midi.File();
+  const track = new import_midi.Track();
+  if (typeof bpm === "number") {
+    track.setTempo(bpm);
+  }
+  file.addTrack(track);
+  for (const noteObj of notes) {
+    const level = noteObj.level || 127;
+    if (noteObj.note) {
+      if (typeof noteObj.note === "string") {
+        track.noteOn(0, noteObj.note, noteObj.length, level);
+        track.noteOff(0, noteObj.note, noteObj.length, level);
+      } else {
+        track.addChord(0, noteObj.note, noteObj.length, level);
+      }
+    } else {
+      track.noteOff(0, "", noteObj.length);
+    }
+  }
+  return file;
+};
+
+// src/progression.ts
+var import_harmonics3 = require("harmonics");
+var getChordDegrees = (mode) => {
+  const theRomans = {
+    ionian: ["I", "ii", "iii", "IV", "V", "vi", "vii\xB0"],
+    dorian: ["i", "ii", "III", "IV", "v", "vi\xB0", "VII"],
+    phrygian: ["i", "II", "III", "iv", "v\xB0", "VI", "vii"],
+    lydian: ["I", "II", "iii", "iv\xB0", "V", "vi", "vii"],
+    mixolydian: ["I", "ii", "iii\xB0", "IV", "v", "vi", "VII"],
+    aeolian: ["i", "ii\xB0", "III", "iv", "v", "VI", "VII"],
+    locrian: ["i\xB0", "II", "iii", "iv", "V", "VI", "vii"],
+    "melodic minor": ["i", "ii", "III+", "IV", "V", "vi\xB0", "vii\xB0"],
+    "harmonic minor": ["i", "ii\xB0", "III+", "iv", "V", "VI", "vii\xB0"]
+  };
+  theRomans.major = theRomans.ionian;
+  theRomans.minor = theRomans.aeolian;
+  return theRomans[mode] || [];
+};
+var idxByDegree = {
+  i: 0,
+  ii: 1,
+  iii: 2,
+  iv: 3,
+  v: 4,
+  vi: 5,
+  vii: 6
+};
+var getChordName = (roman) => {
+  const str = roman.replace(/\W/g, "");
+  let prefix = "M";
+  if (str.toLowerCase() === str) {
+    prefix = "m";
+  }
+  if (roman.indexOf("\xB0") > -1) {
+    return `${prefix}7b5`;
+  }
+  if (roman.indexOf("+") > -1) {
+    return `${prefix}#5`;
+  }
+  if (roman.indexOf("7") > -1) {
+    return prefix === "M" ? "maj7" : "m7";
+  }
+  return prefix;
+};
+var getChordsByProgression = (noteOctaveScale, chordDegress) => {
+  const noteOctaveScaleArr = noteOctaveScale.split(" ");
+  if (!noteOctaveScaleArr[0].match(/\d/)) {
+    noteOctaveScaleArr[0] += "4";
+    noteOctaveScale = noteOctaveScaleArr.join(" ");
+  }
+  const mode = (0, import_harmonics3.scale)(noteOctaveScale);
+  const chordDegreesArr = chordDegress.replace(/\s*,+\s*/g, " ").split(" ");
+  const chordFamily = chordDegreesArr.map((roman) => {
+    const chordName = getChordName(roman);
+    const scaleId = idxByDegree[roman.replace(/\W|\d/g, "").toLowerCase()];
+    const note = mode[scaleId];
+    const oct = note.replace(/\D+/, "");
+    return `${note.replace(/\d/, "") + chordName}_${oct}`;
+  });
+  return chordFamily.toString().replace(/,/g, " ");
+};
+var getProgFactory = ({ T, P, D }) => {
+  return (count = 4) => {
+    const chords = [];
+    chords.push(pickOne(T));
+    let i = 1;
+    if (i < count - 1) {
+      chords.push(pickOne(P));
+      i++;
+    }
+    if (i < count - 1 && dice()) {
+      chords.push(pickOne(P));
+      i++;
+    }
+    if (i < count - 1) {
+      chords.push(pickOne(D));
+      i++;
+    }
+    if (i < count - 1) {
+      chords.push(pickOne(P));
+      i++;
+    }
+    if (i < count - 1) {
+      chords.push(pickOne(D));
+      i++;
+    }
+    if (i < count - 1 && dice()) {
+      chords.push(pickOne(P));
+      i++;
+    }
+    while (i < count) {
+      chords.push(pickOne(D));
+      i++;
+    }
+    return chords;
+  };
+};
+var M = getProgFactory({ T: ["I", "vi"], P: ["ii", "IV"], D: ["V"] });
+var m = getProgFactory({ T: ["i", "VI"], P: ["ii", "iv"], D: ["V"] });
+var progression = (scaleType, count = 4) => {
+  if (scaleType === "major" || scaleType === "M") {
+    return M(count);
+  }
+  if (scaleType === "minor" || scaleType === "m") {
+    return m(count);
+  }
+  return [];
+};
+
+// src/cli.ts
+var HELP_TEXT = `Usage:
+  scribbletune --riff <root> <mode> <pattern> [octaveShift] [motif]
+  scribbletune --chord <root> <mode> <progression|random> <pattern> [subdiv]
+  scribbletune --arp <root> <mode> <progression|random> <pattern> [subdiv]
+
+Examples:
+  scribbletune --riff C3 phrygian x-xRx_RR 0 AABC --sizzle sin 2 --outfile riff.mid
+  scribbletune --chord C3 major 1645 xxxx 1m --sizzle cos 1 --outfile chord.mid
+  scribbletune --chord C3 major CM-FM-Am-GM xxxx 1m
+  scribbletune --chord C3 major random xxxx 1m
+  scribbletune --arp C3 major 1736 xxxx 1m --sizzle cos 4
+
+Options:
+  --outfile <name>      Output MIDI filename (default: music.mid)
+  --bpm <number>        Tempo in BPM
+  --subdiv <value>      Note subdivision (e.g. 4n, 1m)
+  --sizzle [style] [n]  Sizzle style: sin|cos|rampUp|rampDown and optional reps
+  --sizzle-reps <n>     Repetitions for sizzle
+  --amp <0-127>         Maximum note level
+  --accent <pattern>    Accent pattern using x and -
+  --accent-low <0-127>  Accent low level
+  --count <2-8>         Arp note count (arp command only)
+  --order <digits>      Arp order string (arp command only)
+  --fit-pattern         Repeat pattern until it can consume all generated notes (default)
+  --no-fit-pattern      Disable automatic pattern fitting
+  -h, --help            Show this help
+`;
+var romanByDigit = (progDigits, mode) => {
+  const modeForDegrees = mode.toLowerCase();
+  const chordDegrees = getChordDegrees(modeForDegrees);
+  if (!chordDegrees.length) {
+    throw new TypeError(`Unsupported mode "${mode}" for progression digits`);
+  }
+  const romans = progDigits.split("").map((digit) => {
+    const idx = Number(digit) - 1;
+    if (idx < 0 || idx >= chordDegrees.length) {
+      throw new TypeError(`Invalid progression digit "${digit}" in "${progDigits}"`);
+    }
+    return chordDegrees[idx];
+  });
+  return { chordDegrees: romans.join(" "), raw: progDigits };
+};
+var setOctave = (note, octaveShift = 0) => {
+  const base = note.replace(/\d+/g, "");
+  const oct = Number(note.match(/\d+/)?.[0] || "4");
+  return `${base}${oct + octaveShift}`;
+};
+var parseProgression = (root, mode, progressionInput) => {
+  if (progressionInput === "random") {
+    const modeType = mode === "minor" || mode === "m" ? "minor" : "major";
+    const randomProg = progression(modeType, 4).join(" ");
+    return getChordsByProgression(`${root} ${mode}`, randomProg);
+  }
+  if (/^[1-7]+$/.test(progressionInput)) {
+    const converted = romanByDigit(progressionInput, mode);
+    return getChordsByProgression(`${root} ${mode}`, converted.chordDegrees);
+  }
+  if (/^[ivIV°+7\s,]+$/.test(progressionInput)) {
+    const normalized = progressionInput.replace(/\s*,+\s*/g, " ");
+    return getChordsByProgression(`${root} ${mode}`, normalized);
+  }
+  return progressionInput.replace(/-/g, " ");
+};
+var normalizeArpOrder = (order) => {
+  if (!/^\d+$/.test(order)) {
+    throw new TypeError("Invalid value for --order");
+  }
+  if (order.includes("0")) {
+    return order;
+  }
+  return order.split("").map((ch) => {
+    const n = Number(ch);
+    if (n < 1) {
+      throw new TypeError("Invalid value for --order");
+    }
+    return String(n - 1);
+  }).join("");
+};
+var expandPatternSyntax = (pattern) => {
+  const jsRepeatQuoted = pattern.match(/^(['"])(.+)\1\.repeat\((\d+)\)$/);
+  if (jsRepeatQuoted) {
+    return jsRepeatQuoted[2].repeat(Number(jsRepeatQuoted[3]));
+  }
+  const jsRepeatUnquoted = pattern.match(/^(.+)\.repeat\((\d+)\)$/);
+  if (jsRepeatUnquoted) {
+    return jsRepeatUnquoted[1].repeat(Number(jsRepeatUnquoted[2]));
+  }
+  const prefixRepeat = pattern.match(/^(\d+)\((.+)\)$/);
+  if (prefixRepeat) {
+    return prefixRepeat[2].repeat(Number(prefixRepeat[1]));
+  }
+  const suffixRepeat = pattern.match(/^\((.+)\)(\d+)$/);
+  if (suffixRepeat) {
+    return suffixRepeat[1].repeat(Number(suffixRepeat[2]));
+  }
+  return pattern;
+};
+var countPatternSteps = (pattern) => (pattern.match(/[xR]/g) || []).length;
+var fitPatternToNoteCount = (pattern, noteCount) => {
+  const stepCount = countPatternSteps(pattern);
+  if (!stepCount || stepCount >= noteCount) {
+    return pattern;
+  }
+  const reps = Math.ceil(noteCount / stepCount);
+  return pattern.repeat(reps);
+};
+var resolvePattern = (rawPattern, noteCount, fitPattern = false) => {
+  const expanded = expandPatternSyntax(rawPattern);
+  return fitPattern ? fitPatternToNoteCount(expanded, noteCount) : expanded;
+};
+var parseCliArgs = (argv) => {
+  if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+    return null;
+  }
+  let commandArg = argv[0];
+  if (commandArg.startsWith("--")) {
+    commandArg = commandArg.slice(2);
+  }
+  if (commandArg !== "riff" && commandArg !== "chord" && commandArg !== "arp") {
+    throw new TypeError(
+      `First argument must be riff/chord/arp (or --riff/--chord/--arp), received "${argv[0]}"`
+    );
+  }
+  const positionals = [];
+  const options = {
+    command: commandArg,
+    positionals,
+    outfile: "music.mid",
+    fitPattern: true
+  };
+  let i = 1;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (!token.startsWith("--")) {
+      positionals.push(token);
+      i++;
+      continue;
+    }
+    if (token === "--outfile") {
+      options.outfile = argv[i + 1];
+      i += 2;
+      continue;
+    }
+    if (token === "--bpm") {
+      options.bpm = Number(argv[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (token === "--subdiv") {
+      options.subdiv = argv[i + 1];
+      i += 2;
+      continue;
+    }
+    if (token === "--sizzle") {
+      const styleOrNum = argv[i + 1];
+      const maybeNum = argv[i + 2];
+      if (!styleOrNum || styleOrNum.startsWith("--")) {
+        options.sizzle = true;
+        i += 1;
+        continue;
+      }
+      if (/^\d+$/.test(styleOrNum)) {
+        options.sizzle = true;
+        options.sizzleReps = Number(styleOrNum);
+        i += 2;
+        continue;
+      }
+      options.sizzle = styleOrNum;
+      if (maybeNum && /^\d+$/.test(maybeNum)) {
+        options.sizzleReps = Number(maybeNum);
+        i += 3;
+      } else {
+        i += 2;
+      }
+      continue;
+    }
+    if (token === "--sizzle-reps") {
+      options.sizzleReps = Number(argv[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (token === "--amp") {
+      options.amp = Number(argv[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (token === "--accent") {
+      options.accent = argv[i + 1];
+      i += 2;
+      continue;
+    }
+    if (token === "--accent-low") {
+      options.accentLow = Number(argv[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (token === "--count") {
+      options.count = Number(argv[i + 1]);
+      i += 2;
+      continue;
+    }
+    if (token === "--order") {
+      options.order = argv[i + 1];
+      i += 2;
+      continue;
+    }
+    if (token === "--fit-pattern") {
+      options.fitPattern = true;
+      i += 1;
+      continue;
+    }
+    if (token === "--no-fit-pattern") {
+      options.fitPattern = false;
+      i += 1;
+      continue;
+    }
+    throw new TypeError(`Unknown option "${token}"`);
+  }
+  return options;
+};
+var baseClipParams = (parsed) => {
+  return {
+    sizzle: parsed.sizzle,
+    sizzleReps: parsed.sizzleReps,
+    amp: parsed.amp,
+    accent: parsed.accent,
+    accentLow: parsed.accentLow
+  };
+};
+var makeRiff = (parsed) => {
+  const [root, mode, pattern, octaveShiftArg, motif] = parsed.positionals;
+  if (!root || !mode || !pattern) {
+    throw new TypeError(
+      "riff requires: <root> <mode> <pattern> [octaveShift] [motif]"
+    );
+  }
+  const octaveShift = Number(octaveShiftArg || "0");
+  const riffScale = (0, import_harmonics4.scale)(`${setOctave(root, octaveShift)} ${mode}`);
+  const riffNotes = motif && motif.length ? motif.toUpperCase().split("").map((letter) => {
+    const idx = letter.charCodeAt(0) - 65;
+    if (idx < 0) {
+      return riffScale[0];
+    }
+    return riffScale[idx % riffScale.length];
+  }) : riffScale;
+  const resolvedPattern = resolvePattern(
+    pattern,
+    riffNotes.length,
+    parsed.fitPattern
+  );
+  return clip({
+    notes: riffNotes,
+    randomNotes: riffScale,
+    pattern: resolvedPattern,
+    ...baseClipParams(parsed)
+  });
+};
+var makeChord = (parsed) => {
+  const [root, mode, progressionInput, pattern, subdiv] = parsed.positionals;
+  if (!root || !mode || !progressionInput || !pattern) {
+    throw new TypeError(
+      "chord requires: <root> <mode> <progression|random> <pattern> [subdiv]"
+    );
+  }
+  const chords = parseProgression(root, mode, progressionInput);
+  const chordCount = chords.trim().split(/\s+/).length;
+  const resolvedPattern = resolvePattern(pattern, chordCount, parsed.fitPattern);
+  return clip({
+    notes: chords,
+    pattern: resolvedPattern,
+    ...baseClipParams(parsed),
+    subdiv: parsed.subdiv || subdiv
+  });
+};
+var makeArp = (parsed) => {
+  const [root, mode, progressionInput, pattern, subdiv] = parsed.positionals;
+  if (!root || !mode || !progressionInput || !pattern) {
+    throw new TypeError(
+      "arp requires: <root> <mode> <progression|random> <pattern> [subdiv]"
+    );
+  }
+  const chords = parseProgression(root, mode, progressionInput);
+  const arpNotes = arp({
+    chords,
+    count: parsed.count || 4,
+    order: parsed.order ? normalizeArpOrder(parsed.order) : "0123"
+  });
+  const resolvedPattern = resolvePattern(
+    pattern,
+    arpNotes.length,
+    parsed.fitPattern
+  );
+  return clip({
+    notes: arpNotes,
+    pattern: resolvedPattern,
+    ...baseClipParams(parsed),
+    subdiv: parsed.subdiv || subdiv
+  });
+};
+var runCli = (argv, deps) => {
+  const stdout = deps?.stdout || console.log;
+  const stderr = deps?.stderr || console.error;
+  const writeMidi = deps?.writeMidi || ((notes, fileName, bpm) => {
+    midi(notes, fileName, bpm);
+  });
+  try {
+    const parsed = parseCliArgs(argv);
+    if (!parsed) {
+      stdout(HELP_TEXT);
+      return 0;
+    }
+    let notes = [];
+    if (parsed.command === "riff") {
+      notes = makeRiff(parsed);
+    } else if (parsed.command === "chord") {
+      notes = makeChord(parsed);
+    } else {
+      notes = makeArp(parsed);
+    }
+    writeMidi(notes, parsed.outfile, parsed.bpm);
+    stdout(
+      `Generated ${parsed.command} clip (${notes.length} events) -> ${parsed.outfile}`
+    );
+    return 0;
+  } catch (e) {
+    stderr(e instanceof Error ? e.message : String(e));
+    stderr("Run with --help for usage");
+    return 1;
+  }
+};
+if (process.argv[1]?.includes("cli")) {
+  process.exit(runCli(process.argv.slice(2)));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCli
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scribbletune",
-  "version": "5.4.0",
+  "version": "5.5.1",
   "description": "Create music with JavaScript and Node.js!",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -9,6 +9,9 @@
     "dist"
   ],
   "module": "./dist/index.js",
+  "bin": {
+    "scribbletune": "./dist/cli.cjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",