scribbletune 5.2.0 → 5.5.0

package/README.md

@@ -1,41 +1,295 @@
-## <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
+```
+
+#### 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]
+```
+
+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>
+```
+
+#### `--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
 ```
 
-### 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) + '_'
+#### `--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
+```
+
+#### `--arp` examples
+
+```bash
+# Arp from degree progression
+scribbletune --arp C3 major 1736 xxxx 1m --sizzle cos 4 --outfile arp-1736.mid
+
+# Arp from explicit chords
+scribbletune --arp C3 major CM-FM-Am-GM xxxx 1m --count 4 --order 0123 --outfile arp-explicit.mid
+```
+
+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');
+```
+
+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)
+
+```js
+import { clip } from 'scribbletune/browser';
 
-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).
+await Tone.start();
+Tone.Transport.start();
 
-```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>
+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
 
-The recommended way for the browser, however, is to import it like this
-```javascript
-const scribble = require('scribbletune/browser');
+### 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']
 ```
-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).
+### Chord progressions
+
+```js
+import { progression, getChordsByProgression } from 'scribbletune';
+
+progression('M', 4);  // e.g. ['I', 'ii', 'V', 'IV']
+
+getChordsByProgression('C4 major', 'I IV V IV');
+// 'CM_4 FM_4 GM_4 FM_4'
+```
+
+## 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)