scribbletune 5.5.0 → 5.5.1

package/README.md

@@ -39,6 +39,19 @@ 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
@@ -47,6 +60,20 @@ scribbletune --chord <root> <mode> <progression|random> <pattern> [subdiv] [opti
 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
@@ -58,6 +85,23 @@ Common options:
 --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
@@ -68,6 +112,9 @@ 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
@@ -84,6 +131,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,10 +142,29 @@ 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)

package/dist/cli.cjs

@@ -568,6 +568,8 @@ 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)
+  --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) => {
@@ -606,6 +608,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 +672,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 +751,16 @@ var parseCliArgs = (argv) => {
       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,8 +771,7 @@ var baseClipParams = (parsed) => {
     sizzleReps: parsed.sizzleReps,
     amp: parsed.amp,
     accent: parsed.accent,
-    accentLow: parsed.accentLow,
-    subdiv: parsed.subdiv
+    accentLow: parsed.accentLow
   };
 };
 var makeRiff = (parsed) => {
@@ -731,10 +790,15 @@ var makeRiff = (parsed) => {
     }
     return riffScale[idx % riffScale.length];
   }) : riffScale;
+  const resolvedPattern = resolvePattern(
+    pattern,
+    riffNotes.length,
+    parsed.fitPattern
+  );
   return clip({
     notes: riffNotes,
     randomNotes: riffScale,
-    pattern,
+    pattern: resolvedPattern,
     ...baseClipParams(parsed)
   });
 };
@@ -746,11 +810,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 +830,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.1",
   "description": "Create music with JavaScript and Node.js!",
   "type": "module",
   "main": "./dist/index.cjs",