polyphon 0.0.0-stage → 0.1.0

package/src/midi.ts

@@ -0,0 +1,285 @@
+// Read Standard MIDI Files into songs: notes, tempo changes, time signature, sustain pedal, volume and pan.
+// General MIDI programs pick instruments from the built-in orchestra; channel 10 is the drum kit.
+
+import type { BuiltInInstrument } from './instruments/builtin.ts';
+import { stepsPerBar, type Meter, type Note } from './notation/part.ts';
+import type { Song, Track } from './song.ts';
+import type { TempoChange } from './tempo.ts';
+
+export interface MidiImportOptions {
+  /** Song title (default: the file's first track name, or 'Imported MIDI') */
+  title?: string;
+}
+
+/**
+ * Convert a Standard MIDI File (format 0 or 1) into a song that plays once.
+ * Notes stay on the file's beat grid and its tempo changes become the song's, so every event still lands at its real time.
+ *
+ * @example
+ * const song = songFromMidi(await file.arrayBuffer(), { title: file.name });
+ * jukebox.play(song);
+ */
+export function songFromMidi(data: ArrayBuffer | Uint8Array, options: MidiImportOptions = {}): Song {
+  const file = parseMidi(data instanceof Uint8Array ? data : new Uint8Array(data));
+  const step = (tick: number) => (tick / file.ppq) * 4;
+  const signature = file.tracks.flatMap((t) => t.events).find((e) => e.kind === 'meter');
+  const meter: Meter = signature ? `${signature.value}/${signature.denominator}` : 16;
+  const { bpm, tempo } = tempoChanges(file, meter);
+
+  const groups = new Map<string, { name: string; instrument: BuiltInInstrument; gain: number; pan: number; notes: Note[] }>();
+  let end = 0;
+  file.tracks.forEach((track, ti) => {
+    const program = new Array<number>(16).fill(0);
+    const volume = new Array<number | undefined>(16);
+    const pan = new Array<number | undefined>(16);
+    const pedal = new Array<boolean>(16).fill(false);
+    const sounding = new Map<string, { tick: number; velocity: number; program: number }[]>();
+    const held = new Map<number, { key: string; start: { tick: number; velocity: number; program: number } }[]>();
+    const finish = (key: string, start: { tick: number; velocity: number; program: number }, tick: number) => {
+      const [channel, pitch] = key.split('|').map(Number);
+      const drum = channel === 9 ? DRUMS[pitch] : undefined;
+      if (channel === 9 && !drum) return;
+      const instrument = drum ? drum[0] : GM_PROGRAMS[start.program];
+      const id = `${ti}|${channel}|${instrument}`;
+      let g = groups.get(id);
+      if (!g) {
+        const label = drum ? drum[1] : track.name || GM_NAMES[Math.floor(start.program / 8)];
+        g = { name: label, instrument, gain: (volume[channel] ?? 100) / 100, pan: ((pan[channel] ?? 64) - 64) / 64, notes: [] };
+        groups.set(id, g);
+      }
+      const time = step(start.tick);
+      const duration = Math.max(0.25, step(tick) - time);
+      g.notes.push({ time, duration, pitches: drum && !drum[2] ? [] : [pitch], velocity: start.velocity / 127 });
+      end = Math.max(end, time + duration);
+    };
+    for (const e of track.events) {
+      if (e.kind === 'program') program[e.channel] = e.value;
+      else if (e.kind === 'control' && e.control === 7 && volume[e.channel] === undefined) volume[e.channel] = e.value;
+      else if (e.kind === 'control' && e.control === 10 && pan[e.channel] === undefined) pan[e.channel] = e.value;
+      else if (e.kind === 'control' && e.control === 64) {
+        const down = e.value >= 64;
+        if (pedal[e.channel] && !down) for (const h of held.get(e.channel)?.splice(0) ?? []) finish(h.key, h.start, e.tick);
+        pedal[e.channel] = down;
+      } else if (e.kind === 'noteOn') {
+        const key = `${e.channel}|${e.pitch}`;
+        // A key struck again while the pedal holds the old note: the old note ends here
+        const h = held.get(e.channel);
+        const i = h?.findIndex((x) => x.key === key) ?? -1;
+        if (h && i >= 0) finish(key, h.splice(i, 1)[0].start, e.tick);
+        const list = sounding.get(key) ?? [];
+        list.push({ tick: e.tick, velocity: e.velocity, program: program[e.channel] });
+        sounding.set(key, list);
+      } else if (e.kind === 'noteOff') {
+        const key = `${e.channel}|${e.pitch}`;
+        const start = sounding.get(key)?.shift();
+        if (!start) continue;
+        if (pedal[e.channel] && e.channel !== 9) {
+          const h = held.get(e.channel) ?? [];
+          h.push({ key, start });
+          held.set(e.channel, h);
+        } else finish(key, start, e.tick);
+      }
+    }
+    // Notes still sounding or held at the end of the track
+    const last = track.events.length ? track.events[track.events.length - 1].tick : 0;
+    for (const [key, list] of sounding) for (const start of list) finish(key, start, last);
+    for (const h of held.values()) for (const x of h) finish(x.key, x.start, last);
+  });
+
+  const duration = Math.ceil(end);
+  const noteCount = [...groups.values()].reduce((n, g) => n + g.notes.length, 0);
+  const tracks: Track[] = [...groups.values()].map((g) => ({
+    name: g.name,
+    instrument: g.instrument,
+    part: { notes: g.notes.sort((a, b) => a.time - b.time), duration },
+    gain: g.gain,
+    pan: g.pan,
+    repeat: false,
+  }));
+  if (!tracks.length) throw new Error('The MIDI file has no notes');
+  const title = options.title ?? (file.tracks.find((t) => t.name)?.name || 'Imported MIDI');
+  return {
+    title,
+    description: `Imported from MIDI: ${tracks.length} tracks, ${noteCount} notes.`,
+    bpm,
+    ...(tempo.length ? { tempo } : {}),
+    meter,
+    loop: false,
+    tracks,
+  };
+}
+
+// ───────────────────────── Reading the file ─────────────────────────
+
+type MidiEvent =
+  | { kind: 'noteOn' | 'noteOff'; tick: number; channel: number; pitch: number; velocity: number }
+  | { kind: 'control'; tick: number; channel: number; control: number; value: number }
+  | { kind: 'program'; tick: number; channel: number; value: number }
+  | { kind: 'tempo'; tick: number; value: number }
+  | { kind: 'meter'; tick: number; value: number; denominator: number };
+
+interface MidiFile {
+  ppq: number;
+  tracks: { name: string; events: MidiEvent[] }[];
+}
+
+function parseMidi(b: Uint8Array): MidiFile {
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  const text = (at: number, n: number) => String.fromCharCode(...b.subarray(at, at + n));
+  if (text(0, 4) !== 'MThd') throw new Error('Not a MIDI file');
+  const count = view.getUint16(10);
+  const ppq = view.getUint16(12);
+  if (ppq & 0x8000) throw new Error('SMPTE-timed MIDI files are not supported');
+  const tracks: MidiFile['tracks'] = [];
+  let at = 8 + view.getUint32(4);
+  for (let t = 0; t < count && at < b.length; t++) {
+    const length = view.getUint32(at + 4);
+    if (text(at, 4) === 'MTrk') tracks.push(parseTrack(b, at + 8, at + 8 + length));
+    at += 8 + length;
+  }
+  return { ppq, tracks };
+}
+
+function parseTrack(b: Uint8Array, from: number, to: number): MidiFile['tracks'][number] {
+  const events: MidiEvent[] = [];
+  let name = '';
+  let i = from;
+  let tick = 0;
+  let status = 0;
+  const varLen = () => {
+    let v = 0;
+    for (;;) {
+      const c = b[i++];
+      v = (v << 7) | (c & 0x7f);
+      if (!(c & 0x80)) return v;
+    }
+  };
+  while (i < to) {
+    tick += varLen();
+    if (b[i] & 0x80) status = b[i++];
+    if (status === 0xff) {
+      const type = b[i++];
+      const length = varLen();
+      const d = b.subarray(i, i + length);
+      if (type === 0x51) events.push({ kind: 'tempo', tick, value: (d[0] << 16) | (d[1] << 8) | d[2] });
+      else if (type === 0x58) events.push({ kind: 'meter', tick, value: d[0], denominator: 2 ** d[1] });
+      else if (type === 0x03 && !name) name = new TextDecoder().decode(d).trim();
+      i += length;
+      continue;
+    }
+    if (status === 0xf0 || status === 0xf7) {
+      i += varLen();
+      continue;
+    }
+    const channel = status & 0x0f;
+    switch (status & 0xf0) {
+      case 0x90:
+      case 0x80: {
+        const pitch = b[i++];
+        const velocity = b[i++];
+        events.push({ kind: (status & 0xf0) === 0x90 && velocity > 0 ? 'noteOn' : 'noteOff', tick, channel, pitch, velocity });
+        break;
+      }
+      case 0xb0:
+        events.push({ kind: 'control', tick, channel, control: b[i++], value: b[i++] });
+        break;
+      case 0xc0:
+        events.push({ kind: 'program', tick, channel, value: b[i++] });
+        break;
+      case 0xd0:
+        i += 1;
+        break;
+      default:
+        i += 2;
+    }
+  }
+  return { name, events };
+}
+
+/** The opening tempo (default 120) and the changes after it, at the bars where they fall (fractional when mid-bar) */
+function tempoChanges(file: MidiFile, meter: Meter): { bpm: number; tempo: TempoChange[] } {
+  const bar = stepsPerBar(meter);
+  let bpm = 120;
+  const tempo: TempoChange[] = [];
+  const events = file.tracks.flatMap((t) => t.events).filter((e) => e.kind === 'tempo');
+  for (const e of events.sort((a, b) => a.tick - b.tick)) {
+    const value = Math.round(60e8 / e.value) / 100;
+    if (e.tick === 0) bpm = value;
+    else if (value !== (tempo.at(-1)?.bpm ?? bpm)) tempo.push({ bar: 1 + (e.tick / file.ppq) * 4 / bar, bpm: value });
+  }
+  return { bpm, tempo };
+}
+
+// ───────────────────────── General MIDI ─────────────────────────
+
+/** Instrument for each of the 128 General MIDI programs, one family of eight per line */
+const GM_PROGRAMS: BuiltInInstrument[] = [
+  'piano', 'piano', 'piano', 'piano', 'epiano', 'epiano', 'dulcimer', 'piano',
+  'celesta', 'glock', 'musicbox', 'vibes', 'marimba', 'marimba', 'chime', 'dulcimer',
+  'organ', 'organ', 'organ', 'organFull', 'organ', 'accordion', 'accordion', 'accordion',
+  'nylon', 'steel', 'steel', 'steel', 'muteGtr', 'powerGtr', 'powerGtr', 'steel',
+  'pizzBass', 'bass', 'bass', 'bass', 'bass', 'bass', 'synthBass', 'synthBass',
+  'violin', 'violin', 'cello', 'contrabass', 'strings', 'pizz', 'harp', 'timpani',
+  'strings', 'strPad', 'strPad', 'strPad', 'choir', 'choirOo', 'choirO', 'brassStab',
+  'trumpet', 'trombone', 'tuba', 'trumpet', 'horn', 'trumpets', 'trumpets', 'horns',
+  'oboe', 'clarinet', 'clarinet', 'bassoon', 'oboe', 'oboe', 'bassoon', 'clarinet',
+  'flute', 'flute', 'whistle', 'panflute', 'ocarina', 'panflute', 'whistle', 'ocarina',
+  'synthLead', 'synthLead', 'synthLead', 'synthLead', 'synthLead', 'synthLead', 'synthLead', 'synthLead',
+  'warmPad', 'warmPad', 'warmPad', 'choirOo', 'strPad', 'glassPad', 'airPad', 'darkPad',
+  'glassPad', 'glassPad', 'airPad', 'glassPad', 'glassPad', 'darkPad', 'airPad', 'glassPad',
+  'lute', 'steel', 'lute', 'harp', 'kalimba', 'oboe', 'fiddle', 'oboe',
+  'glock', 'woodblock', 'steelpan', 'woodblock', 'taiko', 'tom', 'tom', 'swell',
+  'glassPad', 'glassPad', 'glassPad', 'glassPad', 'glassPad', 'glassPad', 'glassPad', 'glassPad',
+];
+
+/** Display names of the General MIDI families (eight programs each) */
+const GM_NAMES = ['Piano', 'Chromatic percussion', 'Organ', 'Guitar', 'Bass', 'Strings', 'Ensemble', 'Brass', 'Reed', 'Pipe', 'Synth lead', 'Synth pad', 'Synth effects', 'Ethnic', 'Percussive', 'Sound effects'];
+
+/** General MIDI drum keys: [instrument, mixer name, keeps its pitch] */
+const DRUMS: Record<number, [BuiltInInstrument, string, boolean]> = {
+  35: ['kick', 'Kick', false],
+  36: ['kick', 'Kick', false],
+  37: ['rim', 'Rim', false],
+  38: ['snare', 'Snare', false],
+  39: ['clap', 'Clap', false],
+  40: ['snare', 'Snare', false],
+  41: ['tom', 'Toms', true],
+  42: ['hat', 'Hi-hat', false],
+  43: ['tom', 'Toms', true],
+  44: ['hat', 'Hi-hat', false],
+  45: ['tom', 'Toms', true],
+  46: ['ohat', 'Open hi-hat', false],
+  47: ['tom', 'Toms', true],
+  48: ['tom', 'Toms', true],
+  49: ['crash', 'Crash', false],
+  50: ['tom', 'Toms', true],
+  51: ['ride', 'Ride', false],
+  52: ['crash', 'Crash', false],
+  53: ['ride', 'Ride', false],
+  54: ['tamb', 'Tambourine', false],
+  55: ['crash', 'Crash', false],
+  56: ['woodblock', 'Cowbell', true],
+  57: ['crash', 'Crash', false],
+  58: ['shaker', 'Shaker', false],
+  59: ['ride', 'Ride', false],
+  60: ['darbuka', 'Bongos', true],
+  61: ['darbuka', 'Bongos', true],
+  62: ['darbuka', 'Congas', true],
+  63: ['darbuka', 'Congas', true],
+  64: ['darbuka', 'Congas', true],
+  65: ['tom', 'Timbales', true],
+  66: ['tom', 'Timbales', true],
+  67: ['woodblock', 'Agogo', true],
+  68: ['woodblock', 'Agogo', true],
+  69: ['shaker', 'Shaker', false],
+  70: ['shaker', 'Shaker', false],
+  73: ['shaker', 'Shaker', false],
+  74: ['shaker', 'Shaker', false],
+  75: ['clave', 'Claves', false],
+  76: ['woodblock', 'Wood block', true],
+  77: ['woodblock', 'Wood block', true],
+  78: ['darbuka', 'Cuica', true],
+  79: ['darbuka', 'Cuica', true],
+  80: ['triangle', 'Triangle', false],
+  81: ['triangle', 'Triangle', false],
+};

package/src/notation/format.ts

@@ -0,0 +1,96 @@
+// Parts written back as melody strings, the notation melody() reads: for notes that came from elsewhere (a voice, a MIDI file).
+
+import { midi } from '../theory.ts';
+import { stepsPerBar, VELOCITY, type Meter, type Note, type Part } from './part.ts';
+
+const SHARPS = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
+const FLATS = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'];
+/** Without a key signature: each black key as it is most often written (noteName's spelling) */
+const PLAIN = ['C', 'C#', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B'];
+/** Keys whose signatures have flats; the others but C major and A minor have sharps */
+const FLAT_KEYS = new Set(['F', 'Bb', 'Eb', 'Ab', 'Db', 'Gb', 'Cb'].map((t) => `${t} major`).concat(['D', 'G', 'C', 'F', 'Bb', 'Eb', 'Ab'].map((t) => `${t} minor`)));
+
+/**
+ * Write a part as a melody string, with a bar line after every bar; a note that crosses a bar line is tied over it. Black keys are
+ * spelled as the key signature of `key` has them ('Eb major' writes Bb, 'E major' writes D#), or as noteName() does without one.
+ * The notes must follow one another: notes that start together become a chord, and must end together.
+ *
+ * @example
+ * formatMelody(melody('C5:4 E5 G5 C6 | B5:12 r:4 |')); // 'C5:4 E5 G5 C6 | B5:12 r:4 |'
+ * formatMelody(part, '3/4', 'F major');
+ */
+export function formatMelody(part: Part, meter: Meter = 16, key?: string): string {
+  const bar = stepsPerBar(meter);
+  const name = speller(key);
+  const tokens: string[] = [];
+  /** The length in force: a token that leaves its length out reuses it */
+  let length: number | undefined;
+  let time = 0;
+
+  /** Write a note (or a rest, without pitches) from `time`, splitting it at bar lines */
+  const write = (pitches: string | null, duration: number, mark = '', glide = false) => {
+    const end = time + duration;
+    for (let first = true; time < end - 1e-9; first = false) {
+      const barEnd = (Math.floor(time / bar + 1e-9) + 1) * bar;
+      const piece = Math.min(end, barEnd) - time;
+      const last = time + piece >= end - 1e-9;
+      if (pitches === null && Math.abs(piece - bar) < 1e-9) tokens.push('R');
+      else {
+        const written = length !== undefined && Math.abs(piece - length) < 1e-9 ? '' : `:${formatLength(piece)}`;
+        const body = pitches === null ? 'r' : `${first ? mark : ''}${pitches}`;
+        tokens.push(`${body}${written}${pitches !== null && last && glide ? '>' : ''}${pitches !== null && !last ? '~' : ''}`);
+        length = piece;
+      }
+      time += piece;
+      if (Math.abs(time - barEnd) < 1e-9) tokens.push('|');
+    }
+  };
+
+  for (const chord of chords(part.notes)) {
+    const [{ time: start, duration, velocity, glide }] = chord;
+    if (start < time - 1e-9) throw new Error(`Notes overlap at step ${+start.toFixed(3)}: a melody string holds one line`);
+    if (start > time) write(null, start - time);
+    const mark = velocity >= (VELOCITY.accent + VELOCITY.normal) / 2 ? '!' : velocity <= (VELOCITY.normal + VELOCITY.ghost) / 2 ? '?' : '';
+    write(chord.flatMap((n) => n.pitches).map(name).join('+'), duration, mark, glide);
+  }
+  if (part.duration > time) write(null, part.duration - time);
+  return tokens.join(' ');
+}
+
+/** Notes grouped by when they start, in order; a group must end together */
+function chords(notes: readonly Note[]): Note[][] {
+  const groups: Note[][] = [];
+  for (const note of [...notes].sort((a, b) => a.time - b.time)) {
+    const group = groups[groups.length - 1];
+    if (group && Math.abs(group[0].time - note.time) < 1e-9) {
+      if (Math.abs(group[0].duration - note.duration) > 1e-9) throw new Error(`Notes starting together at step ${+note.time.toFixed(3)} must end together`);
+      group.push(note);
+    } else groups.push([note]);
+  }
+  return groups;
+}
+
+/** A length in steps as the notation writes it: 4, or 4/3 for a triplet eighth */
+function formatLength(steps: number): string {
+  for (let denominator = 1; denominator <= 16; denominator++) {
+    const numerator = steps * denominator;
+    if (Math.abs(numerator - Math.round(numerator)) < 1e-6) return denominator === 1 ? `${Math.round(numerator)}` : `${Math.round(numerator)}/${denominator}`;
+  }
+  throw new Error(`A length of ${steps} steps cannot be written`);
+}
+
+/** Note names in a key: its signature's sharps or flats */
+function speller(key?: string): (pitch: number) => string {
+  const names = [...PLAIN];
+  if (key) {
+    const m = /^([A-Ga-g])([#b]?)\s+(major|minor)$/i.exec(key.trim());
+    if (!m) throw new Error(`Unrecognized key: ${key} (write it as 'Eb major' or 'F# minor')`);
+    const [tonic, mode] = [`${m[1].toUpperCase()}${m[2]}`, m[3].toLowerCase()];
+    const plain = (tonic === 'C' && mode === 'major') || (tonic === 'A' && mode === 'minor');
+    if (!plain) names.splice(0, 12, ...(FLAT_KEYS.has(`${tonic} ${mode}`) ? FLATS : SHARPS));
+    // A minor key raises its sixth and seventh on the way up, with sharps or naturals: G# in A minor, C# in D minor
+    const root = midi(`${tonic}4`) % 12;
+    if (mode === 'minor') for (const degree of [9, 11]) names[(root + degree) % 12] = SHARPS[(root + degree) % 12];
+  }
+  return (pitch) => `${names[((pitch % 12) + 12) % 12]}${Math.floor(pitch / 12) - 1}`;
+}

package/src/notation/harmony.ts

@@ -0,0 +1,233 @@
+// Chord progressions, and the parts that grow out of them: pads, arpeggios, bass lines, sustained roots and strums.
+
+import { midi, parseChord, voiceChord, type ChordInfo, type Pitch } from '../theory.ts';
+import { stepsPerBar, VELOCITY, type Meter, type Note, type Part } from './part.ts';
+
+/** A chord placed in time (steps) */
+export interface Chord extends ChordInfo {
+  time: number;
+  duration: number;
+}
+
+/**
+ * Parse a chord progression. Bars are separated by |, and the chords in a bar share it equally;
+ * lengths can also be written out ('C:12 G:4'). '%' holds the previous chord for one more bar.
+ *
+ * @example
+ * chords('Am | F | C G | E7')
+ * chords('Dm:12 A7:4 | %')
+ */
+export function chords(source: string, meter: Meter = 16): Chord[] {
+  const bar = stepsPerBar(meter);
+  const out: Chord[] = [];
+  let t = 0;
+  for (const cell of source.split('|')) {
+    const toks = cell.trim().split(/\s+/).filter(Boolean);
+    if (!toks.length) continue;
+    const explicit = toks.some((x) => x.includes(':'));
+    const each = bar / toks.length;
+    for (const tok of toks) {
+      const [sym, len] = tok.split(':');
+      const d = explicit ? Number(len ?? 0) || each : each;
+      if (sym === '%') {
+        if (out.length) out[out.length - 1].duration += d;
+      } else out.push({ ...parseChord(sym), time: t, duration: d });
+      t += d;
+    }
+  }
+  return out;
+}
+
+/** Total length of a progression, in steps */
+export const chordsDuration = (progression: Chord[]): number => {
+  const last = progression[progression.length - 1];
+  return last ? last.time + last.duration : 0;
+};
+
+export interface PadOptions {
+  /** The register the voicing centers on (default C4) */
+  center?: Pitch;
+  /** Notes per chord (default: every chord tone) */
+  size?: number;
+  velocity?: number;
+  /** Steps of silence before each chord change */
+  gap?: number;
+}
+
+/** Sustained chords (pads, string sections, choirs, organ), voiced to move smoothly */
+export function pad(progression: Chord[], { center = 60, size, velocity = VELOCITY.normal, gap = 0 }: PadOptions = {}): Part {
+  let prev: number[] | undefined;
+  const notes = progression.map((c) => {
+    const m = voiceChord(c, { center, previous: prev, size });
+    prev = m;
+    return { time: c.time, duration: c.duration - gap, pitches: m, velocity };
+  });
+  return { notes, duration: chordsDuration(progression) };
+}
+
+export interface ArpeggioOptions {
+  /** Steps per pattern character (default 2: eighth notes) */
+  step?: number;
+  /** The register the voicing centers on (default E4) */
+  center?: Pitch;
+  /** Notes per chord voicing (default: every chord tone) */
+  size?: number;
+  velocity?: number;
+  /** Accent every Nth note */
+  accent?: number;
+}
+
+/**
+ * Arpeggio: the pattern picks chord tones by digit (0 is the lowest; past the number of chord tones it climbs an octave);
+ * '.' is a rest, '-' holds the previous note. The pattern restarts on every chord.
+ *
+ * @example
+ * arpeggio(chords('C | Am'), '0 1 2 1')
+ * arpeggio(chords('C | Am'), '0-12 3.21', { step: 1, center: 'C5' })
+ */
+export function arpeggio(progression: Chord[], pattern: string, { step = 2, center = 64, size, velocity = VELOCITY.normal, accent }: ArpeggioOptions = {}): Part {
+  const pat = pattern.replace(/\s+/g, '');
+  const notes: Note[] = [];
+  let prev: number[] | undefined;
+  for (const c of progression) {
+    const vc = voiceChord(c, { center, previous: prev, size });
+    prev = vc;
+    let k = 0;
+    for (let s = 0; s < c.duration - 1e-6; s += step, k++) {
+      const ch = pat[k % pat.length];
+      if (ch === '.') continue;
+      if (ch === '-') {
+        if (notes.length) notes[notes.length - 1].duration += step;
+        continue;
+      }
+      const idx = parseInt(ch, 36);
+      const n = vc.length;
+      const m = vc[idx % n] + 12 * Math.floor(idx / n);
+      const acc = accent && k % accent === 0 ? 1.15 : 1;
+      notes.push({ time: c.time + s, duration: Math.min(step, c.duration - s), pitches: [m], velocity: Math.min(1, velocity * acc) });
+    }
+  }
+  return { notes, duration: chordsDuration(progression) };
+}
+
+/** What to stack above the bass: prefer a perfect fifth; if there is none (diminished chord, inversion, passing bass), look in turn for a sixth, a fourth, a third */
+const ABOVE = [7, 8, 9, 5, 4, 3, 6];
+
+/** The chord's bass note, placed within a fifth below to a fifth above the register */
+function bassNote(c: Chord, register: number): number {
+  let low = register + ((c.bass - (register % 12) + 12) % 12);
+  if (low > register + 7) low -= 12;
+  return low;
+}
+
+export interface RootsOptions {
+  /** Where the bass sits: notes land within a fifth below to a fifth above this pitch (default C2) */
+  register?: Pitch;
+  /** Stack one more chord tone on top (usually an open fifth) */
+  fifth?: boolean;
+  velocity?: number;
+}
+
+/** Sustained bass notes: one per chord, held for the whole chord; a repeated bass note continues without re-attacking */
+export function roots(progression: Chord[], { register = 36, fifth = false, velocity = 0.8 }: RootsOptions = {}): Part {
+  const reg = midi(register);
+  const notes: Note[] = [];
+  for (const c of progression) {
+    // Passing bass (a slash bass that is not a chord tone): just follows the bass, with no fifth stacked (stacking it would clash with the chord)
+    const pcs = new Set(c.intervals.map((i) => (c.root + i) % 12));
+    const low = bassNote(c, reg);
+    const m = [low];
+    if (fifth && pcs.has(c.bass)) {
+      const up = ABOVE.find((k) => pcs.has((c.bass + k) % 12));
+      if (up !== undefined) m.push(low + up);
+    }
+    const last = notes[notes.length - 1];
+    if (last && last.pitches.join() === m.join() && last.time + last.duration === c.time) last.duration += c.duration;
+    else notes.push({ time: c.time, duration: c.duration, pitches: m, velocity });
+  }
+  return { notes, duration: chordsDuration(progression) };
+}
+
+export interface BasslineOptions {
+  /** Where the bass sits: the chord's bass lands within a fifth below to a fifth above this pitch (default C2) */
+  register?: Pitch;
+  velocity?: number;
+}
+
+/**
+ * Bass line: the rhythm is a rhythm string that repeats every bar ('-' holds), and the line lists the scale degrees used in turn:
+ * 1 the chord's bass, 3 the chord's third, 5 the fifth, 8 an octave up, -8 an octave down, b7 / 7 / 2 / 4 / 6, b2 (Phrygian), -5 / -4 below.
+ *
+ * @example
+ * bassline(chords('C | Am | F | G'), 'x.x.x.x.x.x.x.x.', '1 5 8 5')
+ */
+export function bassline(progression: Chord[], rhythm: string, line = '1', { register = 36, velocity = VELOCITY.normal }: BasslineOptions = {}): Part {
+  const rh = rhythm.replace(/[\s|]/g, '');
+  const steps = line.trim().split(/\s+/);
+  const reg = midi(register);
+  const notes: Note[] = [];
+  let li = 0;
+  for (const c of progression) {
+    const low = bassNote(c, reg);
+    // Other degrees are counted from the root, placed at the nearest position above the bass
+    const rootAbove = low + ((c.root - c.bass + 12) % 12);
+    for (let s = 0; s < c.duration; s++) {
+      const ch = rh[(c.time + s) % rh.length];
+      if (ch === '-') {
+        if (notes.length) notes[notes.length - 1].duration += 1;
+        continue;
+      }
+      if (ch !== 'x' && ch !== 'X' && ch !== 'o') continue;
+      const deg = steps[li++ % steps.length];
+      let m: number;
+      if (deg === '1') m = low;
+      else if (deg === '8') m = low + 12;
+      else if (deg === '-8') m = low - 12;
+      else {
+        m = rootAbove + degreeOffset(deg, c);
+        if (!deg.startsWith('-')) while (m < low) m += 12;
+      }
+      notes.push({ time: c.time + s, duration: 1, pitches: [m], velocity: ch === 'X' ? 1 : ch === 'o' ? 0.5 : velocity });
+    }
+  }
+  return { notes, duration: chordsDuration(progression) };
+}
+
+function degreeOffset(deg: string, c: ChordInfo): number {
+  const fifth = c.intervals.includes(6) && !c.intervals.includes(7) ? 6 : c.intervals.includes(8) ? 8 : 7;
+  const map: Record<string, number> = { '1': 0, b2: 1, '2': 2, b3: 3, '3': c.third || 4, '4': 5, b5: 6, '5': fifth, b6: 8, '6': 9, b7: 10, '7': 11, '8': 12, '10': 12 + (c.third || 4), '-5': -5, '-4': -7, '-b7': -2, '-7': -1, '-8': -12 };
+  const v = map[deg];
+  if (v === undefined) throw new Error(`Unrecognized bass scale degree: ${deg}`);
+  return v;
+}
+
+export interface StrumOptions {
+  /** The register the voicing centers on (default Bb3) */
+  center?: Pitch;
+  /** Strings per strum (default 5) */
+  size?: number;
+  /** Seconds between strings (default 0.014) */
+  spread?: number;
+  velocity?: number;
+}
+
+/** Strummed chords: the rhythm repeats every bar, x down-stroke, X heavy, o soft, '-' holds */
+export function strum(progression: Chord[], rhythm: string, { center = 58, size = 5, spread = 0.014, velocity = VELOCITY.normal }: StrumOptions = {}): Part {
+  const rh = rhythm.replace(/[\s|]/g, '');
+  const notes: Note[] = [];
+  let prev: number[] | undefined;
+  for (const c of progression) {
+    const vc = voiceChord(c, { center, previous: prev, size });
+    prev = vc;
+    for (let s = 0; s < c.duration; s++) {
+      const ch = rh[(c.time + s) % rh.length];
+      if (ch === '-') {
+        if (notes.length) notes[notes.length - 1].duration += 1;
+        continue;
+      }
+      if (ch !== 'x' && ch !== 'X' && ch !== 'o') continue;
+      notes.push({ time: c.time + s, duration: 1, pitches: vc, velocity: ch === 'X' ? 1 : ch === 'o' ? 0.5 : velocity, strum: spread });
+    }
+  }
+  return { notes, duration: chordsDuration(progression) };
+}