@hum2music/arrangement 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@hum2music/arrangement",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Rule-based Piano/Bass/Drums/Guitar arrangers and style profiles for Hum2Music.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/hum2music/hum2music",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hum2music/hum2music.git",
+    "directory": "packages/arrangement"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["src"],
+  "dependencies": {
+    "@hum2music/core": "0.1.0",
+    "@hum2music/music-theory": "0.1.0",
+    "@hum2music/expression": "0.1.0",
+    "@hum2music/harmony": "0.1.0"
+  }
+}

package/src/bass.ts

@@ -0,0 +1,50 @@
+import type { ChordEvent, NoteEvent } from "@hum2music/core";
+import { parseChordSymbol, pitchClassOf } from "@hum2music/music-theory";
+import type { ArrangementContext, InstrumentArranger } from "./types";
+
+const ROOT_OCTAVE_BASE_PITCH = 36; // the C in "C2", i.e. lowestPitchInOctave(0, ...) = 36
+const VELOCITY = 75;
+const APPROACH_VELOCITY = 65;
+
+/**
+ * Root-driven bass: holds the chord root through beats 1-2, repeats it on
+ * beat 3, then on beat 4 plays a chromatic approach note into the next
+ * chord's root (or holds the root again on the final bar). Lands on the
+ * same strong beats (1 and 3) as the drum arranger's kick, approximating
+ * "kick sync" without reading the drum track directly (PRD §9.3).
+ */
+export function generateBassArrangement(chords: ChordEvent[]): NoteEvent[] {
+  const notes: NoteEvent[] = [];
+
+  chords.forEach((chord, index) => {
+    const parsed = parseChordSymbol(chord.symbol);
+    if (!parsed) return;
+
+    const quarter = chord.durationBeats / 4;
+    const rootPitch = lowestPitchInOctave(parsed.root);
+
+    notes.push(note(rootPitch, chord.startBeat, quarter * 2, VELOCITY));
+    notes.push(note(rootPitch, chord.startBeat + quarter * 2, quarter, VELOCITY));
+
+    const nextChord = chords[index + 1];
+    const nextParsed = nextChord ? parseChordSymbol(nextChord.symbol) : null;
+    const lastBeatPitch = nextParsed ? lowestPitchInOctave(nextParsed.root) - 1 : rootPitch;
+    const lastBeatVelocity = nextParsed ? APPROACH_VELOCITY : VELOCITY;
+
+    notes.push(note(lastBeatPitch, chord.startBeat + quarter * 3, quarter, lastBeatVelocity));
+  });
+
+  return notes;
+}
+
+function lowestPitchInOctave(pitchClass: number): number {
+  return ROOT_OCTAVE_BASE_PITCH + pitchClassOf(pitchClass);
+}
+
+function note(pitch: number, startBeat: number, durationBeats: number, velocity: number): NoteEvent {
+  return { pitch, startBeat, durationBeats, velocity };
+}
+
+export const bassArranger: InstrumentArranger = {
+  generate: (context: ArrangementContext) => generateBassArrangement(context.chords),
+};

package/src/compose.ts

@@ -0,0 +1,85 @@
+import type { ChordEvent, NoteEvent, SongSection } from "@hum2music/core";
+import { generateBassArrangement } from "./bass";
+import { generateDrumArrangement } from "./drums";
+import { generateGuitarArrangement } from "./guitar";
+import { generatePianoArrangement } from "./piano";
+import { applySectionalHumanization } from "./sectional-humanize";
+import { resolveStyleProfile, type StyleProfile } from "./style";
+
+export const ARRANGEABLE_INSTRUMENTS = ["piano", "bass", "drums", "guitar"] as const;
+export type ArrangeableInstrument = (typeof ARRANGEABLE_INSTRUMENTS)[number];
+
+export interface ComposedTrack {
+  instrument: "melody" | ArrangeableInstrument;
+  notes: NoteEvent[];
+  channel: number;
+  programNumber?: number;
+}
+
+export interface ComposeTracksOptions {
+  melody: NoteEvent[];
+  chords: ChordEvent[];
+  instruments?: Iterable<ArrangeableInstrument>;
+  humanizeAmount?: number;
+  seed?: number;
+  bpm: number;
+  /** Defaults to the "pop" profile; see style.ts. Governs pattern choice, voicing extensions, drum density, and GM program numbers. */
+  style?: StyleProfile | string;
+  /** When given (and non-empty), humanization intensity varies per bar by repeated section (see sectional-humanize.ts) instead of one flat amount. */
+  songSections?: SongSection[];
+}
+
+const DEFAULT_SEED = 42;
+const CHANNELS: Record<ArrangeableInstrument, number> = { piano: 1, bass: 2, drums: 9, guitar: 3 };
+
+/**
+ * Builds the melody track plus any requested arranged instrument tracks
+ * (piano/bass/drums/guitar), optionally humanized per-track. Shared by the
+ * CLI's `generate` command and the web UI's export endpoints so
+ * arrangement + humanization logic lives in exactly one place.
+ */
+export function composeTracks(options: ComposeTracksOptions): ComposedTrack[] {
+  const style = resolveStyle(options.style);
+  const included = new Set(options.instruments ?? ARRANGEABLE_INSTRUMENTS);
+
+  const tracks: ComposedTrack[] = [{ instrument: "melody", notes: options.melody, channel: 0 }];
+
+  if (included.has("piano")) {
+    const notes = generatePianoArrangement(options.chords, {
+      pattern: style.pianoPattern,
+      allowExtensions: style.pianoAllowExtensions,
+    });
+    tracks.push({ instrument: "piano", notes, channel: CHANNELS.piano, programNumber: style.programNumbers.piano });
+  }
+  if (included.has("bass")) {
+    const notes = generateBassArrangement(options.chords);
+    tracks.push({ instrument: "bass", notes, channel: CHANNELS.bass, programNumber: style.programNumbers.bass });
+  }
+  if (included.has("drums")) {
+    const notes = generateDrumArrangement(options.chords, { density: style.drumDensity });
+    tracks.push({ instrument: "drums", notes, channel: CHANNELS.drums });
+  }
+  if (included.has("guitar")) {
+    const notes = generateGuitarArrangement(options.chords, { pattern: style.guitarPattern });
+    tracks.push({ instrument: "guitar", notes, channel: CHANNELS.guitar, programNumber: style.programNumbers.guitar });
+  }
+
+  const humanizeAmount = options.humanizeAmount ?? 0;
+  if (humanizeAmount <= 0) return tracks;
+
+  const seed = options.seed ?? DEFAULT_SEED;
+  const sections = options.songSections ?? [];
+  return tracks.map((track) => ({
+    ...track,
+    notes: applySectionalHumanization(track.notes, sections, {
+      baseAmount: Math.min(1, humanizeAmount * style.humanizeMultiplier),
+      seed,
+      bpm: options.bpm,
+      instrument: track.instrument,
+    }),
+  }));
+}
+
+function resolveStyle(style: StyleProfile | string | undefined): StyleProfile {
+  return typeof style === "string" || style === undefined ? resolveStyleProfile(style) : style;
+}

package/src/drums.ts

@@ -0,0 +1,59 @@
+import type { ChordEvent, NoteEvent } from "@hum2music/core";
+import type { ArrangementContext, InstrumentArranger } from "./types";
+
+/** General MIDI percussion map note numbers. */
+export const KICK_PITCH = 36;
+export const SNARE_PITCH = 38;
+export const CLOSED_HIHAT_PITCH = 42;
+
+const HIT_DURATION_BEATS = 0.1;
+const VELOCITY = { kick: 100, snare: 95, hihat: 70 };
+
+export interface DrumArrangementOptions {
+  /** "sparse" drops to a half-time feel (kick on 1 only, snare on 3 only, quarter-note hi-hat) for e.g. a ballad. */
+  density?: "normal" | "sparse";
+}
+
+/**
+ * One bar of the basic 4/4 backbeat per bar (kick on 1 & 3, snare on 2 & 4,
+ * eighth-note closed hi-hat throughout), per PRD §10.3's example pattern.
+ * `density: "sparse"` is the one documented variation beyond this fixed
+ * template; further variation is left to future work.
+ */
+export function generateDrumArrangement(chords: ChordEvent[], options: DrumArrangementOptions = {}): NoteEvent[] {
+  const density = options.density ?? "normal";
+  const notes: NoteEvent[] = [];
+
+  for (const chord of chords) {
+    const quarter = chord.durationBeats / 4;
+    const eighth = quarter / 2;
+
+    if (density === "sparse") {
+      notes.push(hit(KICK_PITCH, chord.startBeat, VELOCITY.kick));
+      notes.push(hit(SNARE_PITCH, chord.startBeat + quarter * 2, VELOCITY.snare));
+      for (let quarterIndex = 0; quarterIndex < 4; quarterIndex++) {
+        notes.push(hit(CLOSED_HIHAT_PITCH, chord.startBeat + quarterIndex * quarter, VELOCITY.hihat));
+      }
+      continue;
+    }
+
+    notes.push(hit(KICK_PITCH, chord.startBeat, VELOCITY.kick));
+    notes.push(hit(KICK_PITCH, chord.startBeat + quarter * 2, VELOCITY.kick));
+    notes.push(hit(SNARE_PITCH, chord.startBeat + quarter, VELOCITY.snare));
+    notes.push(hit(SNARE_PITCH, chord.startBeat + quarter * 3, VELOCITY.snare));
+
+    for (let eighthIndex = 0; eighthIndex < 8; eighthIndex++) {
+      notes.push(hit(CLOSED_HIHAT_PITCH, chord.startBeat + eighthIndex * eighth, VELOCITY.hihat));
+    }
+  }
+
+  return notes;
+}
+
+function hit(pitch: number, startBeat: number, velocity: number): NoteEvent {
+  return { pitch, startBeat, durationBeats: HIT_DURATION_BEATS, velocity };
+}
+
+export const drumsArranger: InstrumentArranger = {
+  generate: (context: ArrangementContext) => generateDrumArrangement(context.chords),
+};

package/src/guitar.ts

@@ -0,0 +1,100 @@
+import type { ChordEvent, NoteEvent } from "@hum2music/core";
+import { chordPitchClasses, parseChordSymbol, pitchClassOf } from "@hum2music/music-theory";
+import type { ArrangementContext, InstrumentArranger } from "./types";
+
+/** Standard tuning, low to high string (open-string MIDI pitches): E2 A2 D3 G3 B3 E4. */
+const OPEN_STRING_PITCHES = [40, 45, 50, 55, 59, 64];
+/** Max frets apart a single hand position can comfortably cover. */
+const MAX_FRET_SPAN = 3;
+/** How far up the neck to search for a playable voicing before giving up on a string. */
+const MAX_FRET_SEARCH = 9;
+
+const DOWN_STROKE_VELOCITY = 80;
+const UP_STROKE_VELOCITY = 60;
+const STROKE_DURATION_FRACTION = 0.9;
+
+export interface GuitarArrangementOptions {
+  pattern?: "strum" | "arpeggio";
+}
+
+/**
+ * Finds a playable chord shape (one fret-window position, each string
+ * either muted or fretted within that window) and plays it as either a
+ * strummed down/up pattern or a simple arpeggio. Never generates a shape
+ * that would require a fret span wider than a hand can cover (PRD §9.4).
+ */
+export function generateGuitarArrangement(chords: ChordEvent[], options: GuitarArrangementOptions = {}): NoteEvent[] {
+  const pattern = options.pattern ?? "strum";
+  const notes: NoteEvent[] = [];
+
+  for (const chord of chords) {
+    const parsed = parseChordSymbol(chord.symbol);
+    if (!parsed) continue;
+
+    const chordTones = new Set(chordPitchClasses(parsed.root, parsed.quality));
+    const voicing = findPlayableVoicing(chordTones);
+    if (voicing.length === 0) continue;
+
+    const quarter = chord.durationBeats / 4;
+    if (pattern === "arpeggio") {
+      voicing.forEach((pitch, index) => {
+        const beatOffset = (index % 4) * quarter;
+        notes.push({
+          pitch,
+          startBeat: chord.startBeat + beatOffset,
+          durationBeats: quarter * STROKE_DURATION_FRACTION,
+          velocity: DOWN_STROKE_VELOCITY,
+        });
+      });
+      continue;
+    }
+
+    for (let beatIndex = 0; beatIndex < 4; beatIndex++) {
+      const isDownStroke = beatIndex % 2 === 0;
+      const velocity = isDownStroke ? DOWN_STROKE_VELOCITY : UP_STROKE_VELOCITY;
+      for (const pitch of voicing) {
+        notes.push({
+          pitch,
+          startBeat: chord.startBeat + beatIndex * quarter,
+          durationBeats: quarter * STROKE_DURATION_FRACTION,
+          velocity,
+        });
+      }
+    }
+  }
+
+  return notes;
+}
+
+/** Scans fret-window positions and returns the one that sounds the most strings. */
+function findPlayableVoicing(chordTones: Set<number>): number[] {
+  let best: number[] = [];
+
+  for (let windowStart = 0; windowStart <= MAX_FRET_SEARCH; windowStart++) {
+    const pitches: number[] = [];
+    for (const openPitch of OPEN_STRING_PITCHES) {
+      const fret = findFretInWindow(openPitch, windowStart, chordTones);
+      if (fret !== null) pitches.push(openPitch + fret);
+    }
+    if (pitches.length > best.length) best = pitches;
+    if (best.length === OPEN_STRING_PITCHES.length) break;
+  }
+
+  return best;
+}
+
+function findFretInWindow(openPitch: number, windowStart: number, chordTones: Set<number>): number | null {
+  const frets = windowStart === 0 ? [0, 1, 2, 3] : range(windowStart, windowStart + MAX_FRET_SPAN);
+  for (const fret of frets) {
+    if (chordTones.has(pitchClassOf(openPitch + fret))) return fret;
+  }
+  return null;
+}
+
+function range(start: number, end: number): number[] {
+  return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+}
+
+export const guitarArranger: InstrumentArranger = {
+  generate: (context: ArrangementContext) => generateGuitarArrangement(context.chords),
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./types";
+export * from "./piano";
+export * from "./bass";
+export * from "./drums";
+export * from "./guitar";
+export * from "./style";
+export * from "./sectional-humanize";
+export * from "./compose";

package/src/piano.ts

@@ -0,0 +1,105 @@
+import type { ChordEvent, NoteEvent } from "@hum2music/core";
+import { chordPitchClasses, parseChordSymbol, pitchClassOf } from "@hum2music/music-theory";
+import type { ArrangementContext, InstrumentArranger } from "./types";
+
+const MIN_PITCH = 48; // C3
+const MAX_PITCH = 72; // C5
+const VELOCITY = 70;
+const NINTH_INTERVAL_SEMITONES = 2;
+
+export interface PianoArrangementOptions {
+  pattern?: "block" | "arpeggio";
+  /** Lets the voicing search also place the 9th, for a richer/"more advanced" sound (docs/specs/style-profiles.md). */
+  allowExtensions?: boolean;
+}
+
+/**
+ * For each bar, picks the voicing (octave placement of the chord's tones,
+ * optionally plus the 9th) within the piano's range with the smallest total
+ * movement from the previous bar's voicing, rather than always using the
+ * same inversion (PRD §9.2). Played either as a sustained block chord or a
+ * simple ascending arpeggio across the bar.
+ */
+export function generatePianoArrangement(chords: ChordEvent[], options: PianoArrangementOptions = {}): NoteEvent[] {
+  const pattern = options.pattern ?? "block";
+  const notes: NoteEvent[] = [];
+  let previousVoicing: number[] | null = null;
+
+  for (const chord of chords) {
+    const parsed = parseChordSymbol(chord.symbol);
+    if (!parsed) continue;
+
+    const toneClasses = chordPitchClasses(parsed.root, parsed.quality);
+    const availableTones = options.allowExtensions
+      ? [...toneClasses, pitchClassOf(parsed.root + NINTH_INTERVAL_SEMITONES)]
+      : toneClasses;
+
+    const voicing = chooseVoicing(availableTones, previousVoicing);
+    previousVoicing = voicing;
+
+    if (pattern === "arpeggio") {
+      const quarter = chord.durationBeats / 4;
+      voicing.forEach((pitch, index) => {
+        notes.push({
+          pitch,
+          startBeat: chord.startBeat + (index % 4) * quarter,
+          durationBeats: quarter * 0.9,
+          velocity: VELOCITY,
+        });
+      });
+      continue;
+    }
+
+    for (const pitch of voicing) {
+      notes.push({ pitch, startBeat: chord.startBeat, durationBeats: chord.durationBeats, velocity: VELOCITY });
+    }
+  }
+
+  return notes;
+}
+
+function chooseVoicing(toneClasses: number[], previousVoicing: number[] | null): number[] {
+  const candidates = enumerateVoicingsInRange(toneClasses);
+  if (candidates.length === 0) return toneClasses.map((pc) => pc + 60);
+  if (!previousVoicing) return candidates[0];
+
+  let best = candidates[0];
+  let bestMovement = totalVoiceMovement(previousVoicing, best);
+  for (const candidate of candidates.slice(1)) {
+    const movement = totalVoiceMovement(previousVoicing, candidate);
+    if (movement < bestMovement) {
+      best = candidate;
+      bestMovement = movement;
+    }
+  }
+  return best;
+}
+
+function enumerateVoicingsInRange(toneClasses: number[]): number[][] {
+  const optionsPerTone = toneClasses.map((pitchClass) => {
+    const options: number[] = [];
+    for (let pitch = MIN_PITCH; pitch <= MAX_PITCH; pitch++) {
+      if (pitchClassOf(pitch) === pitchClass) options.push(pitch);
+    }
+    return options;
+  });
+
+  let combinations: number[][] = [[]];
+  for (const options of optionsPerTone) {
+    const next: number[][] = [];
+    for (const combo of combinations) {
+      for (const option of options) next.push([...combo, option]);
+    }
+    combinations = next;
+  }
+
+  return combinations.map((combo) => [...combo].sort((a, b) => a - b));
+}
+
+function totalVoiceMovement(previous: number[], candidate: number[]): number {
+  return candidate.reduce((sum, pitch) => sum + Math.min(...previous.map((p) => Math.abs(p - pitch))), 0);
+}
+
+export const pianoArranger: InstrumentArranger = {
+  generate: (context: ArrangementContext) => generatePianoArrangement(context.chords),
+};

package/src/sectional-humanize.ts

@@ -0,0 +1,59 @@
+import type { NoteEvent, SongSection } from "@hum2music/core";
+import { deriveSectionalHumanizeAmount, humanizeMelody } from "@hum2music/expression";
+
+const BEATS_PER_BAR = 4;
+
+export interface SectionalHumanizeOptions {
+  baseAmount: number;
+  seed: number;
+  bpm: number;
+  instrument: string;
+}
+
+/**
+ * Humanizes a track bar-by-bar, varying intensity by song section (via
+ * deriveSectionalHumanizeAmount) instead of applying one flat amount to
+ * the whole track. Note: each bar re-seeds its own random stream from the
+ * same track sub-seed, so notes at the same position-within-bar across
+ * different bars can draw correlated (not fully independent) jitter —
+ * still fully deterministic/reproducible, just less varied than a single
+ * continuous stream would be. Documented tradeoff, not a bug.
+ */
+export function applySectionalHumanization(
+  notes: NoteEvent[],
+  sections: SongSection[],
+  options: SectionalHumanizeOptions,
+): NoteEvent[] {
+  if (options.baseAmount <= 0) return notes;
+  if (sections.length === 0) {
+    return humanizeMelody(notes, {
+      seed: options.seed,
+      humanizeAmount: options.baseAmount,
+      bpm: options.bpm,
+      instrument: options.instrument,
+    });
+  }
+
+  const notesByBar = new Map<number, NoteEvent[]>();
+  for (const note of notes) {
+    const barIndex = Math.floor(note.startBeat / BEATS_PER_BAR);
+    const bucket = notesByBar.get(barIndex) ?? [];
+    bucket.push(note);
+    notesByBar.set(barIndex, bucket);
+  }
+
+  const result: NoteEvent[] = [];
+  for (const [barIndex, barNotes] of notesByBar) {
+    const amount = deriveSectionalHumanizeAmount(options.baseAmount, sections, barIndex);
+    result.push(
+      ...humanizeMelody(barNotes, {
+        seed: options.seed,
+        humanizeAmount: amount,
+        bpm: options.bpm,
+        instrument: options.instrument,
+      }),
+    );
+  }
+
+  return result;
+}

package/src/style.ts

@@ -0,0 +1,55 @@
+import type { ProgressionSearchWeights } from "@hum2music/harmony";
+
+export type StyleName = "pop" | "ballad";
+export const STYLE_NAMES: StyleName[] = ["pop", "ballad"];
+
+export interface StyleProfile {
+  name: StyleName;
+  /** Passed through to searchChordProgression; style-dependent weighting stands in for the S term (PRD §8.3). */
+  harmonyWeights: ProgressionSearchWeights;
+  pianoPattern: "block" | "arpeggio";
+  /** Whether the piano voicing may add the 9th as an extra available tone, beyond the chord's own tones. */
+  pianoAllowExtensions: boolean;
+  guitarPattern: "strum" | "arpeggio";
+  drumDensity: "normal" | "sparse";
+  humanizeMultiplier: number;
+  programNumbers: { piano: number; bass: number; guitar: number };
+}
+
+/**
+ * A style is a weighting/parameter profile layered on top of the existing
+ * engines, not a new generation algorithm, to keep everything deterministic
+ * (PRD §15.1) and the engines swappable (docs/specs/style-profiles.md).
+ * Proposed values below are unvalidated starting points.
+ */
+export const STYLE_PROFILES: Record<StyleName, StyleProfile> = {
+  pop: {
+    name: "pop",
+    harmonyWeights: { melodyFit: 0.5, harmonicNaturalness: 0.3, voiceLeading: 0.2 },
+    pianoPattern: "block",
+    pianoAllowExtensions: false,
+    guitarPattern: "strum",
+    drumDensity: "normal",
+    humanizeMultiplier: 1,
+    programNumbers: { piano: 0, bass: 33, guitar: 29 },
+  },
+  ballad: {
+    name: "ballad",
+    harmonyWeights: { melodyFit: 0.55, harmonicNaturalness: 0.25, voiceLeading: 0.2 },
+    pianoPattern: "arpeggio",
+    pianoAllowExtensions: true,
+    guitarPattern: "arpeggio",
+    drumDensity: "sparse",
+    humanizeMultiplier: 0.7,
+    programNumbers: { piano: 0, bass: 32, guitar: 24 },
+  },
+};
+
+export function resolveStyleProfile(name: string | undefined): StyleProfile {
+  if (name && isStyleName(name)) return STYLE_PROFILES[name];
+  return STYLE_PROFILES.pop;
+}
+
+function isStyleName(name: string): name is StyleName {
+  return (STYLE_NAMES as string[]).includes(name);
+}

package/src/types.ts

@@ -0,0 +1,11 @@
+import type { ChordEvent, NoteEvent } from "@hum2music/core";
+
+/** Everything an arranger needs: a chord progression (one chord per bar, per harmony's grouping). */
+export interface ArrangementContext {
+  chords: ChordEvent[];
+}
+
+/** Common interface so each instrument's arranger is independently swappable (PRD §9.1). */
+export interface InstrumentArranger {
+  generate(context: ArrangementContext): NoteEvent[];
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.