scribbletune 5.5.0 → 5.5.2

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Scribbletune</h1>
 
 <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>.
+  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> or use the CLI to directly emit MIDI file from your terminal.
 </p>
 
 <p align="center">
@@ -23,9 +23,9 @@ npm install scribbletune
 
 ## Quick start
 
-### CLI
+### Option 1: CLI
 
-The package now ships a CLI binary: `scribbletune`.
+If you installed Scribbletune globally via `npm i -g scribbletune` then you can directly use `scribbletune` as the command. If you installed it locally via `npm i scribbletune` then please use `npx scribbletune` as the command.
 
 Run modes:
 
@@ -39,25 +39,55 @@ npm install scribbletune
 npx scribbletune --help
 ```
 
+Quick command examples:
+
 #### Command format
 
 ```bash
-scribbletune --riff <root> <mode> <pattern> [octaveShift] [motif] [options]
+scribbletune --riff <root> <mode> <pattern> [subdiv] [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 (`root` and `mode` are ignored)
+```
+
 Common options:
 
 ```bash
---outfile <file.mid>    # default: music.mid
---bpm <number>
+--outfile <file.mid>  # default: music.mid
 --subdiv <4n|8n|1m...>
 --sizzle [sin|cos|rampUp|rampDown] [reps]
 --sizzle-reps <number>
 --amp <0-127>
 --accent <x--x...>
 --accent-low <0-127>
+--style <letters>     # riff motif/style, e.g. AABC
+--fit-pattern         # explicit enable (already enabled by default)
+--no-fit-pattern      # disable automatic pattern fitting
+--bpm <number>        # your DAW may or may not support it
+```
+
+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
@@ -66,10 +96,21 @@ Common options:
 # 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
+# With motif/style and positional subdiv
+scribbletune --riff C3 phrygian x-xRx_RR 8n --style AABC --sizzle sin 2 --outfile riff-aabc.mid
+
+# Set riff subdivision via positional arg
+scribbletune --riff C3 phrygian x-xRx_RR 8n --style AABC --outfile riff-8n.mid
+
+# Pattern with subdivisions (quote [] in shell)
+scribbletune --riff C3 phrygian 'x-x[xx]-x-[xx]' 8n --style AABC --outfile riff-subdiv.mid
 ```
 
+Riff + motif note:
+- `--style` creates riff sections by repeating the full pattern per letter.
+- Example: `--style AABC` with pattern `x-x[xx]` creates 4 sections: `A`, `A`, `B`, `C`.
+- Repeated letters reuse the exact same generated section (same rhythm and same notes, including random `R` choices).
+
 #### `--chord` examples
 
 ```bash
@@ -84,6 +125,9 @@ 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
@@ -92,13 +136,32 @@ scribbletune --chord C3 major CM-FM-Am-GM xxxx 1m --outfile chords-explicit.mid
 # 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 0123 --outfile arp-explicit.mid
+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)
+### Option 2: Node.js
 
 ```js
 import { scale, clip, midi } from 'scribbletune';
@@ -111,7 +174,7 @@ midi(c, 'c-major.mid');
 
 Run it with `node` and open the `.mid` file in Ableton Live, GarageBand, Logic, or any DAW.
 
-### Play in the browser (with Tone.js)
+### Option 3: 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/).
 
@@ -286,6 +349,12 @@ npm run lint      # check with biome
 npm run dev       # build in watch mode
 ```
 
+If developing new features for the CLI, use the following command after running `npm run build` to test before publishing,
+
+```bash
+node dist/cli.cjs --help
+```
+
 ## License
 
 MIT

package/dist/cli.cjs

@@ -546,12 +546,12 @@ var progression = (scaleType, count = 4) => {
 
 // src/cli.ts
 var HELP_TEXT = `Usage:
-  scribbletune --riff <root> <mode> <pattern> [octaveShift] [motif]
+  scribbletune --riff <root> <mode> <pattern> [subdiv]
   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 --riff C3 phrygian x-xRx_RR 8n --style 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
@@ -568,6 +568,9 @@ Options:
   --accent-low <0-127>  Accent low level
   --count <2-8>         Arp note count (arp command only)
   --order <digits>      Arp order string (arp command only)
+  --style <letters>     Riff motif/style pattern (e.g. AABC)
+  --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) => {
@@ -585,11 +588,6 @@ var romanByDigit = (progDigits, mode) => {
   });
   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";
@@ -606,6 +604,53 @@ var parseProgression = (root, mode, progressionInput) => {
   }
   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;
@@ -623,7 +668,8 @@ var parseCliArgs = (argv) => {
   const options = {
     command: commandArg,
     positionals,
-    outfile: "music.mid"
+    outfile: "music.mid",
+    fitPattern: true
   };
   let i = 1;
   while (i < argv.length) {
@@ -701,6 +747,21 @@ var parseCliArgs = (argv) => {
       i += 2;
       continue;
     }
+    if (token === "--style") {
+      options.style = 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;
@@ -711,31 +772,57 @@ var baseClipParams = (parsed) => {
     sizzleReps: parsed.sizzleReps,
     amp: parsed.amp,
     accent: parsed.accent,
-    accentLow: parsed.accentLow,
-    subdiv: parsed.subdiv
+    accentLow: parsed.accentLow
   };
 };
 var makeRiff = (parsed) => {
-  const [root, mode, pattern, octaveShiftArg, motif] = parsed.positionals;
+  const [root, mode, pattern, subdiv] = parsed.positionals;
+  const style = parsed.style;
   if (!root || !mode || !pattern) {
-    throw new TypeError(
-      "riff requires: <root> <mode> <pattern> [octaveShift] [motif]"
-    );
+    throw new TypeError("riff requires: <root> <mode> <pattern> [subdiv]");
   }
-  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];
+  const riffScale = (0, import_harmonics4.scale)(`${root} ${mode}`);
+  let riffNotes = riffScale;
+  let resolvedPattern = resolvePattern(
+    pattern,
+    riffNotes.length,
+    parsed.fitPattern
+  );
+  if (style && style.length) {
+    const sectionPattern = expandPatternSyntax(pattern);
+    const letters = style.toUpperCase().split("");
+    const sectionCache = {};
+    const combined = [];
+    const clipParams = {
+      ...baseClipParams(parsed),
+      subdiv: parsed.subdiv || subdiv
+    };
+    for (const letter of letters) {
+      if (!sectionCache[letter]) {
+        const idx = letter.charCodeAt(0) - 65;
+        const note = riffScale[idx >= 0 ? idx % riffScale.length : 0];
+        sectionCache[letter] = clip({
+          notes: [note],
+          randomNotes: riffScale,
+          pattern: sectionPattern,
+          ...clipParams
+        });
+      }
+      combined.push(
+        ...sectionCache[letter].map((event) => ({
+          ...event,
+          note: event.note ? [...event.note] : null
+        }))
+      );
     }
-    return riffScale[idx % riffScale.length];
-  }) : riffScale;
+    return combined;
+  }
   return clip({
     notes: riffNotes,
     randomNotes: riffScale,
-    pattern,
-    ...baseClipParams(parsed)
+    pattern: resolvedPattern,
+    ...baseClipParams(parsed),
+    subdiv: parsed.subdiv || subdiv
   });
 };
 var makeChord = (parsed) => {
@@ -746,11 +833,13 @@ var makeChord = (parsed) => {
     );
   }
   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,
-    subdiv: parsed.subdiv || subdiv,
-    ...baseClipParams(parsed)
+    pattern: resolvedPattern,
+    ...baseClipParams(parsed),
+    subdiv: parsed.subdiv || subdiv
   });
 };
 var makeArp = (parsed) => {
@@ -764,13 +853,18 @@ var makeArp = (parsed) => {
   const arpNotes = arp({
     chords,
     count: parsed.count || 4,
-    order: parsed.order || "0123"
+    order: parsed.order ? normalizeArpOrder(parsed.order) : "0123"
   });
+  const resolvedPattern = resolvePattern(
+    pattern,
+    arpNotes.length,
+    parsed.fitPattern
+  );
   return clip({
     notes: arpNotes,
-    pattern,
-    subdiv: parsed.subdiv || subdiv,
-    ...baseClipParams(parsed)
+    pattern: resolvedPattern,
+    ...baseClipParams(parsed),
+    subdiv: parsed.subdiv || subdiv
   });
 };
 var runCli = (argv, deps) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scribbletune",
-  "version": "5.5.0",
+  "version": "5.5.2",
   "description": "Create music with JavaScript and Node.js!",
   "type": "module",
   "main": "./dist/index.cjs",