polyphon 0.0.0-stage → 0.1.0

package/src/notation/melody.ts

@@ -0,0 +1,133 @@
+// Melodies and rhythms written as short strings.
+//
+// Melody:
+//   'E5:4 D5:2 C5:2 | B4:8 r:8 |'   note:length in sixteenth-note steps, r is a rest, | is a bar line (each bar's length is checked)
+//   'E5:4 D5 C5 B4'                  leave out the length to reuse the previous one
+//   'C4+E4+G4:16'                    a chord (pitches sounding together)
+//   '!E5:4 ?E5:2'                    ! accent, ? soft (ghost note)
+//   'E5:4> G5:4'                     > glide into the next note (instruments that support glides)
+//   'G4:8~ | G4:4'                   ~ ties into the next note of the same pitch, across bar lines too
+//   'E5:4/3'                         fractional length (a triplet eighth note is 4/3)
+//   '(E5:2 D5:2)*4 R*2'              parenthesized groups repeat; R is a full bar of rest; . is the same as r
+//
+// Rhythm: one character per step. X accent, x normal, o soft, . or - rest; spaces and | are ignored.
+
+import { midi, type Pitch } from '../theory.ts';
+import { stepsPerBar, VELOCITY, type Meter, type Note, type Part } from './part.ts';
+
+/**
+ * Parse a melody string.
+ *
+ * @example
+ * melody('C5:4 E5 G5 C6 | B5:8 G5:8 |')
+ * melody('G4:6 A4:2 B4:4 | D5:12 |', '3/4')
+ */
+export function melody(source: string, meter: Meter = 16): Part {
+  const bar = stepsPerBar(meter);
+  const notes: Note[] = [];
+  let t = 0;
+  let dur = 4;
+  let barStart = 0;
+  let barNo = 1;
+  let lastR = false;
+  /** The note a ~ holds on into the next one */
+  let tied: Note | undefined;
+  for (const raw of expandRepeats(source).split(/\s+/)) {
+    if (!raw) continue;
+    if (raw === '|') {
+      // R is a complete bar by itself, so a bar line right after it needs no further check (the "R*3 |" style)
+      if (lastR && Math.abs(t - barStart) < 1e-6) {
+        lastR = false;
+        continue;
+      }
+      if (Math.abs(t - barStart - bar) > 1e-6) throw new Error(`Bar ${barNo} is ${+(t - barStart).toFixed(3)} steps long, expected ${bar}: ...${source.slice(0, 60)}`);
+      barStart = t;
+      barNo++;
+      continue;
+    }
+    if (raw === 'R') {
+      if (tied) throw new Error(`A tie (~) must lead into the same note, not a rest: ${raw}`);
+      const atBar = Math.abs(t - barStart) < 1e-6;
+      t += bar;
+      if (atBar) {
+        barStart = t;
+        barNo++;
+      }
+      lastR = atBar;
+      continue;
+    }
+    lastR = false;
+    let tok = raw;
+    let v: number = VELOCITY.normal;
+    if (tok[0] === '!') {
+      v = VELOCITY.accent;
+      tok = tok.slice(1);
+    } else if (tok[0] === '?') {
+      v = VELOCITY.ghost;
+      tok = tok.slice(1);
+    }
+    const tie = tok.endsWith('~');
+    if (tie) tok = tok.slice(0, -1);
+    let glide = false;
+    if (tok.endsWith('>')) {
+      glide = true;
+      tok = tok.slice(0, -1);
+    }
+    const [pitch, len] = tok.split(':');
+    if (len) {
+      const [a, b] = len.split('/');
+      dur = b ? Number(a) / Number(b) : Number(a);
+      if (!(dur > 0)) throw new Error(`Invalid duration: ${raw}`);
+    }
+    if (pitch === 'r' || pitch === '.') {
+      if (tied || tie) throw new Error(`A tie (~) joins two notes of the same pitch, not a rest: ${raw}`);
+    } else if (tied) {
+      if (pitch.split('+').map(midi).join() !== tied.pitches.join()) throw new Error(`A tie (~) must lead into the same pitch: ${raw}`);
+      tied.duration += dur;
+      if (glide) tied.glide = true;
+    } else notes.push({ time: t, duration: dur, pitches: pitch.split('+').map(midi), velocity: v, glide: glide || undefined });
+    tied = tie ? notes[notes.length - 1] : undefined;
+    t += dur;
+  }
+  if (tied) throw new Error('A tie (~) at the end of a melody has no note to lead into');
+  return { notes, duration: t };
+}
+
+function expandRepeats(src: string): string {
+  let s = src.replace(/\|/g, ' | ');
+  // Expand parentheses from the inside out
+  for (let guard = 0; guard < 50 && s.includes('('); guard++) {
+    s = s.replace(/\(([^()]*)\)\*(\d+)/g, (_, body: string, n: string) => Array(Number(n)).fill(body).join(' '));
+    s = s.replace(/\(([^()]*)\)(?!\*)/g, (_, body: string) => body);
+  }
+  // Repeat a single token: R*4, E5:2*3
+  s = s.replace(/(\S+)\*(\d+)/g, (_, tok: string, n: string) => Array(Number(n)).fill(tok).join(' '));
+  return s;
+}
+
+export interface RhythmOptions {
+  /** Steps per character (default 1: each character is a sixteenth note) */
+  step?: number;
+  /** The pitch every hit plays (tuned drums, or any instrument); default: unpitched */
+  pitch?: Pitch;
+}
+
+/**
+ * Parse a rhythm: one character per step. X accent, x normal, o soft, . or - rest.
+ *
+ * @example
+ * rhythm('X...x...X..xx...')            // a kick pattern
+ * rhythm('x.x.x.x.', { pitch: 'G2' })   // a pitched pulse
+ */
+export function rhythm(pattern: string, { step = 1, pitch }: RhythmOptions = {}): Part {
+  const m = pitch === undefined ? undefined : midi(pitch);
+  const notes: Note[] = [];
+  let t = 0;
+  for (const ch of pattern) {
+    if (ch === ' ' || ch === '|' || ch === '\n') continue;
+    const v = ch === 'X' ? VELOCITY.accent : ch === 'x' ? VELOCITY.normal : ch === 'o' ? VELOCITY.ghost : 0;
+    if (v) notes.push({ time: t, duration: step, pitches: m === undefined ? [] : [m], velocity: v });
+    t += step;
+  }
+  return { notes, duration: t };
+}

package/src/notation/part.ts

@@ -0,0 +1,42 @@
+// The data every notation function produces: a Part is a list of notes on a grid of sixteenth-note steps.
+// It is plain data, so any code that returns { notes, duration } can feed a track.
+
+/** One note (or chord) in a part. Times are in steps: one step is a sixteenth note. */
+export interface Note {
+  /** Start, in steps from the start of the part */
+  time: number;
+  /** Length, in steps */
+  duration: number;
+  /** MIDI pitches sounding together; unpitched drums may leave this empty */
+  pitches: number[];
+  /** Loudness 0-1 */
+  velocity: number;
+  /** Glide into the next note (instruments that support glides) */
+  glide?: boolean;
+  /** Strum a chord: delay in seconds between successive pitches */
+  strum?: number;
+}
+
+export interface Part {
+  notes: Note[];
+  /** Total length, in steps */
+  duration: number;
+}
+
+/**
+ * A time signature, or the number of sixteenth-note steps in one bar.
+ * '4/4' = 16, '3/4' = 12, '6/8' = 12, '7/8' = 14, '5/4' = 20.
+ */
+export type Meter = number | `${number}/${number}`;
+
+/** Steps in one bar of a meter (default 4/4 = 16) */
+export function stepsPerBar(meter: Meter = 16): number {
+  if (typeof meter === 'number') return meter;
+  const [beats, unit] = meter.split('/').map(Number);
+  const steps = (beats * 16) / unit;
+  if (!(steps > 0) || !Number.isFinite(steps)) throw new Error(`Invalid meter: ${meter}`);
+  return steps;
+}
+
+/** Velocities for the three dynamics the notation can write */
+export const VELOCITY = { normal: 0.78, accent: 1, ghost: 0.42 } as const;

package/src/notation/transform.ts

@@ -0,0 +1,78 @@
+// Combine and reshape parts. Every function returns a new part; nothing is modified in place.
+
+import type { Chord } from './harmony.ts';
+import { melody } from './melody.ts';
+import { stepsPerBar, type Meter, type Note, type Part } from './part.ts';
+
+const asPart = (p: Part | string): Part => (typeof p === 'string' ? melody(p) : p);
+
+/** Play parts one after another (strings are read as 4/4 melodies) */
+export function sequence(...parts: (Part | string)[]): Part {
+  const notes: Note[] = [];
+  let t = 0;
+  for (const p of parts.map(asPart)) {
+    for (const n of p.notes) notes.push({ ...n, time: n.time + t });
+    t += p.duration;
+  }
+  return { notes, duration: t };
+}
+
+/** Play parts at the same time; the result is as long as the longest */
+export function stack(...parts: Part[]): Part {
+  return { notes: parts.flatMap((p) => p.notes).sort((a, b) => a.time - b.time), duration: Math.max(0, ...parts.map((p) => p.duration)) };
+}
+
+/** Play a part n times in a row */
+export function repeat(part: Part, times: number): Part {
+  return sequence(...Array<Part>(times).fill(part));
+}
+
+/** Silence for a number of bars */
+export const rest = (bars: number, meter: Meter = 16): Part => ({ notes: [], duration: bars * stepsPerBar(meter) });
+
+/** Shift every pitch by a number of semitones */
+export function transpose(part: Part, semitones: number): Part {
+  return mapPitch(part, (m) => m + semitones);
+}
+
+/** Rewrite every pitch (for mode changes, inversions and so on) */
+export function mapPitch(part: Part, fn: (midi: number) => number): Part {
+  return { notes: part.notes.map((n) => ({ ...n, pitches: n.pitches.map(fn) })), duration: part.duration };
+}
+
+/** Multiply every velocity (0.5 = half as loud; capped at 1) */
+export function scaleVelocity(part: Part, factor: number): Part {
+  return { notes: part.notes.map((n) => ({ ...n, velocity: Math.min(1, n.velocity * factor) })), duration: part.duration };
+}
+
+/** Cut out the steps [from, to); notes that run past the end are shortened */
+export function slice(part: Part, from: number, to: number): Part {
+  return {
+    notes: part.notes.filter((n) => n.time >= from && n.time < to).map((n) => ({ ...n, time: n.time - from, duration: Math.min(n.duration, to - n.time) })),
+    duration: to - from,
+  };
+}
+
+/**
+ * The sustain pedal: every note rings on until the next pedal change, or until its key is struck again.
+ * Changes are given as a step interval (16: once a bar), a list of steps, or a chord progression (change with each chord).
+ *
+ * @example
+ * pedal(arpeggio(harmony, '0 1 2 1'), harmony)   // re-pedal on every chord
+ * pedal(melody('...'), 16)                       // once a bar
+ */
+export function pedal(part: Part, changes: number | number[] | Chord[]): Part {
+  const points =
+    typeof changes === 'number'
+      ? Array.from({ length: Math.ceil(part.duration / changes) }, (_, i) => (i + 1) * changes)
+      : changes.map((c) => (typeof c === 'number' ? c : c.time)).sort((a, b) => a - b);
+  const nextChange = (t: number) => points.find((p) => p > t + 1e-9) ?? part.duration;
+  const nextStrike = (t: number, pitches: number[]) => {
+    const later = part.notes.filter((n) => n.time > t + 1e-9 && n.pitches.some((m) => pitches.includes(m)));
+    return later.length ? Math.min(...later.map((n) => n.time)) : Infinity;
+  };
+  return {
+    notes: part.notes.map((n) => ({ ...n, duration: Math.max(n.duration, Math.min(nextChange(n.time), nextStrike(n.time, n.pitches)) - n.time) })),
+    duration: part.duration,
+  };
+}

package/src/song.ts

@@ -0,0 +1,170 @@
+// A song is plain data: tempo, the room it plays in, and tracks that pair an instrument with a part.
+
+import type { Room } from './instruments/dsp/reverb.ts';
+import type { InstrumentName } from './instruments/registry.ts';
+import { melody } from './notation/melody.ts';
+import { stepsPerBar, type Meter, type Part } from './notation/part.ts';
+import { tempoClock, type TempoChange } from './tempo.ts';
+
+export interface Song {
+  title: string;
+  /** One line on the mood and the instrumentation */
+  description?: string;
+  /** Beats (quarter notes) per minute: the tempo the song starts at */
+  bpm: number;
+  /** Changes of tempo along the way: at once (a new section) or gliding (ritardando, accelerando) */
+  tempo?: TempoChange[];
+  /** Dead stops: moments where everything falls silent, the room's echo too, before the music crashes back in */
+  silences?: Silence[];
+  /** Time signature (default '4/4') */
+  meter?: Meter;
+  /** Eighth-note swing 0-0.5 (0.33 is roughly a triplet feel) */
+  swing?: number;
+  /** Sixteenth-note swing 0-0.5 */
+  swing16?: number;
+  /** The room (default: a medium hall) */
+  reverb?: Reverb;
+  /** A tempo-synced stereo ping-pong delay that tracks can send to */
+  delay?: Delay;
+  /** Level of the whole song (linear, default 1) */
+  gain?: number;
+  /** Mastering: EQ, glue compression and, for loud genres, a limiter */
+  master?: Master;
+  /** Plays once before the tracks start looping */
+  intro?: Track[];
+  /** The body of the song; loops unless `loop` is false */
+  tracks: Track[];
+  /** false: play the body once and end (jingles, fanfares). Default true */
+  loop?: boolean;
+}
+
+export interface Track {
+  /** Shown in mixers; defaults to the instrument name */
+  name?: string;
+  instrument: InstrumentName;
+  /** The notes: a part, or a melody string read in the song's meter */
+  part: Part | string;
+  /** Level (linear, default 1) */
+  gain?: number;
+  /** -1 left to 1 right */
+  pan?: number;
+  /** How much goes to the reverb, 0-1 (default 0.25) */
+  reverb?: number;
+  /** How much goes to the delay, 0-1 (default 0) */
+  delay?: number;
+  /** Duck under another track's hits, the pumping of house and EDM: that track's name (usually 'Kick'), or how deep and how long too */
+  duck?: string | Duck;
+  /** Low-pass filter: a cutoff in Hz, or a sweep */
+  lowpass?: number | Sweep;
+  /** High-pass filter: a cutoff in Hz, or a sweep */
+  highpass?: number | Sweep;
+  /** Semitones */
+  transpose?: number;
+  /** Timing looseness: the most a note may land early or late, in seconds (default 0.008, drums 0.003) */
+  humanize?: number;
+  /** Instrument settings, such as attack, release, bright, glide */
+  params?: Record<string, number>;
+  /** false: play once at the start of the section instead of repeating to fill it. Default true */
+  repeat?: boolean;
+}
+
+/**
+ * A dead stop from `bar` (counted from 1 at the start of the song, the intro's bars first; fractional to start mid-bar, so 32.75 is the
+ * last beat of bar 32) for `beats` quarter notes. Everything falls silent, the reverb and delay tails too, as if the room were switched off,
+ * and comes back at full level when it ends. A silence in the body happens on every pass.
+ */
+export interface Silence {
+  bar: number;
+  beats: number;
+}
+
+export interface Reverb extends Room {
+  /** Level of the reverb return (default 1) */
+  mix?: number;
+}
+
+export interface Delay {
+  /** Delay time, in sixteenth-note steps at the song's opening tempo */
+  steps: number;
+  /** Echo feedback 0-1 (default 0.35) */
+  feedback?: number;
+  /** Low-pass on the echoes, Hz (default 2800) */
+  tone?: number;
+  /** Level of the delay return (default 0.8) */
+  mix?: number;
+}
+
+/** Sidechain pumping: at every hit of another track (usually the kick) the level dips, then swells back */
+export interface Duck {
+  /** The name of the track whose hits duck this one, in the same section (it pumps even while that track is muted) */
+  by: string;
+  /** How far the level dips, 0-1 (default 0.7) */
+  depth?: number;
+  /** Steps until it is back up, at the song's opening tempo (default 4: a beat) */
+  release?: number;
+}
+
+/**
+ * A filter sweep, { step: Hz }, counted from the start of the section: the cutoff glides from one to the next (evenly in pitch) and
+ * holds before the first and after the last. `{ 0: 400, 128: 400, 256: 18000 }` stays dark for eight bars, then opens over eight more.
+ */
+export type Sweep = Record<number, number>;
+
+export interface Master {
+  /** Body at 150 Hz, dB */
+  warm?: number;
+  /** Pulls 1.3 kHz down, dB */
+  cut?: number;
+  /** Level of the mix, dB */
+  trim?: number;
+  /** Bus compression that glues the mix together, 0-1 (0.3 gentle, 0.6 firm) */
+  glue?: number;
+  /** Master loud: dB pushed into a brickwall limiter that keeps the peaks under -1 dBFS, between the samples too (EDM: about 6-10). The song then bypasses the gentle limiter other songs share */
+  loud?: number;
+}
+
+export const DEFAULT_REVERB: Reverb = { size: 1.8, damp: 0.45 };
+
+/**
+ * Declare a song. It returns the song unchanged; it exists so editors can type-check and autocomplete it.
+ *
+ * @example
+ * export default defineSong({
+ *   title: 'Morning Market',
+ *   bpm: 112,
+ *   tracks: [
+ *     { instrument: 'marimba', part: 'C5:2 E5 G5 E5 | D5:4 B4:4 G4:8 |' },
+ *     { instrument: 'pizzBass', part: bassline(chords('C | G'), 'x...x...x...x...', '1 5') },
+ *   ],
+ * });
+ */
+export function defineSong(song: Song): Song {
+  return song;
+}
+
+/** A track's name: its own, or its instrument's */
+export function trackName(track: Track): string {
+  return track.name ?? track.instrument;
+}
+
+/** The part a track plays (melody strings are read in the song's meter) */
+export function trackPart(track: Track, meter: Meter): Part {
+  return typeof track.part === 'string' ? melody(track.part, meter) : track.part;
+}
+
+/** Length of a section whose tracks have these parts: the longest, rounded up to whole bars (at least one bar) */
+export function sectionSteps(parts: Part[], meter: Meter): number {
+  const bar = stepsPerBar(meter);
+  const longest = Math.max(bar, ...parts.map((p) => p.duration));
+  return Math.ceil(longest / bar - 1e-6) * bar;
+}
+
+/** How long the intro and one pass of the body last, in seconds */
+export function songDuration(song: Song): { intro: number; loop: number } {
+  const meter = song.meter ?? 16;
+  const steps = (tracks: Track[]) => sectionSteps(tracks.map((t) => trackPart(t, meter)), meter);
+  const clock = tempoClock(song);
+  const introSteps = song.intro?.length ? steps(song.intro) : 0;
+  const intro = clock.seconds(introSteps);
+  return { intro, loop: clock.seconds(introSteps + steps(song.tracks)) - intro };
+}

package/src/tempo.ts

@@ -0,0 +1,108 @@
+// Tempo through a song: changes at once (a new section) or gradually (ritardando, accelerando), and the clock that turns positions in
+// the score into seconds.
+
+import { stepsPerBar, type Meter } from './notation/part.ts';
+
+/**
+ * A change of tempo at the start of a bar, counted from 1 at the start of the song (the intro's bars first, then the body's).
+ * `{ bar: 90, bpm: 66 }` is a new tempo from bar 90; `{ bar: 120, bpm: 80, over: 4 }` slows down evenly to 80 across bars 120 to 123.
+ * A bar may be fractional to change mid-bar: 12.5 is halfway through bar 12.
+ */
+export interface TempoChange {
+  bar: number;
+  /** Beats (quarter notes) per minute */
+  bpm: number;
+  /** How many bars the change takes, gliding evenly from the tempo before it (default 0: at once) */
+  over?: number;
+}
+
+/** A song's tempo through its score: positions in steps from the start of the song, as seconds and back */
+export interface TempoClock {
+  /** Seconds from the start of the song to a step */
+  seconds(step: number): number;
+  /** The step the song has reached after `seconds` */
+  step(seconds: number): number;
+  /** Beats per minute at a step */
+  bpm(step: number): number;
+}
+
+/** A stretch of the score from `step` to the next span: the tempo starts at `bpm` and glides by `slope` per step (0: holds) */
+interface Span {
+  step: number;
+  bpm: number;
+  /** Seconds from the start of the song */
+  seconds: number;
+  /** Change in bpm per step */
+  slope: number;
+}
+
+/** Seconds a step lasts at a tempo: 60 / bpm / 4 */
+const stepSeconds = (bpm: number) => 15 / bpm;
+
+/**
+ * The clock of a song (its `bpm`, `tempo` and `meter`). Each pass of a looping body plays the same changes: the body's steps follow
+ * the intro's, so a body step's time within its pass is `seconds(introSteps + step) - seconds(introSteps)`.
+ *
+ * @example
+ * const clock = tempoClock({ bpm: 120, meter: '3/4', tempo: [{ bar: 9, bpm: 60 }] });
+ * clock.seconds(8 * 12 + 4); // 12 + 0.25 * 4 = 13: eight bars at 120, then a beat at 60
+ */
+export function tempoClock({ bpm, tempo = [], meter }: { bpm: number; tempo?: readonly TempoChange[]; meter?: Meter }): TempoClock {
+  const bar = stepsPerBar(meter);
+  if (!(bpm > 0)) throw new Error(`Invalid tempo: ${bpm} bpm`);
+  const spans: Span[] = [{ step: 0, bpm, seconds: 0, slope: 0 }];
+  /** Hold or glide from the end of the last span to `step`, arriving at `target` bpm */
+  const to = (step: number, target: number) => {
+    const last = spans[spans.length - 1];
+    if (step <= last.step) return;
+    last.slope = (target - last.bpm) / (step - last.step);
+    spans.push({ step, bpm: target, seconds: last.seconds + within(last, step - last.step), slope: 0 });
+  };
+  for (const change of [...tempo].sort((a, b) => a.bar - b.bar)) {
+    const start = (change.bar - 1) * bar;
+    const end = start + (change.over ?? 0) * bar;
+    const before = spans[spans.length - 1];
+    if (!(change.bpm > 0) || !(change.bar >= 1) || !(end >= start)) throw new Error(`Invalid tempo change: ${JSON.stringify(change)}`);
+    if (start < before.step - 1e-9) throw new Error(`The tempo change at bar ${change.bar} starts before the change before it has finished`);
+    to(start, before.bpm);
+    if (end > start) to(end, change.bpm);
+    else spans[spans.length - 1].bpm = change.bpm;
+  }
+  /** The last span starting at or before `value` (a MIDI file's rubato can make thousands) */
+  const spanAt = (key: 'step' | 'seconds', value: number) => {
+    let lo = 0;
+    let hi = spans.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (spans[mid][key] <= value) lo = mid;
+      else hi = mid - 1;
+    }
+    return spans[lo];
+  };
+  return {
+    seconds: (step) => {
+      const span = spanAt('step', step);
+      return span.seconds + within(span, step - span.step);
+    },
+    step: (seconds) => {
+      const span = spanAt('seconds', seconds);
+      return span.step + stepsWithin(span, seconds - span.seconds);
+    },
+    bpm: (step) => {
+      const span = spanAt('step', step);
+      return span.bpm + span.slope * Math.max(0, step - span.step);
+    },
+  };
+}
+
+/** Seconds for the first `steps` of a span: the tempo glides linearly, so the time is the integral of 15 / bpm(step) */
+function within({ bpm, slope }: Span, steps: number): number {
+  if (Math.abs(slope) < 1e-12 || steps <= 0) return steps * stepSeconds(bpm);
+  return (15 / slope) * Math.log(1 + (slope * steps) / bpm);
+}
+
+/** Steps a span covers in its first `seconds` (the inverse of `within`) */
+function stepsWithin({ bpm, slope }: Span, seconds: number): number {
+  if (Math.abs(slope) < 1e-12 || seconds <= 0) return seconds / stepSeconds(bpm);
+  return (bpm / slope) * Math.expm1((slope * seconds) / 15);
+}