hum2music 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# hum2music
 
-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.
+Turn a hummed melody into a multi-track MIDI/WAV song — no generative AI, a
+local, rule-based engine built on signal processing and music theory.
+
+Full docs, architecture, and source: https://github.com/hum2music/hum2music
+
+## Requirements
+
+This CLI runs on [Bun](https://bun.sh) (the published entry point is a `.ts`
+file executed directly by Bun, not pre-compiled JavaScript).
+
+## Usage
+
+```bash
+bunx hum2music transcribe input.wav -o melody.mid
+bunx hum2music analyze input.wav --chords
+bunx hum2music generate input.wav -o song.mid --wav song.wav
+bunx hum2music serve --port 3000
+```
+
+## License
+
+Apache License 2.0

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "hum2music",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Turn a hummed melody into a multi-track MIDI/WAV song — no generative AI, a local, rule-based CLI built on music theory and signal processing.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/hum2music/hum2music",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hum2music/hum2music.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "midi",
+    "music",
+    "cli",
+    "humming",
+    "melody-transcription",
+    "music-theory",
+    "composition"
+  ],
+  "type": "module",
+  "bin": {
+    "hum2music": "./src/index.ts"
+  },
+  "files": ["src", "README.md"],
+  "dependencies": {
+    "@hum2music/audio-analysis": "0.1.0",
+    "@hum2music/midi": "0.1.0",
+    "@hum2music/harmony": "0.1.0",
+    "@hum2music/expression": "0.1.0",
+    "@hum2music/web": "0.1.0",
+    "@hum2music/arrangement": "0.1.0",
+    "@hum2music/rendering": "0.1.0"
+  }
+}

package/src/commands/analyze.ts

@@ -0,0 +1,88 @@
+import { parseArgs } from "node:util";
+import { decodeWav, transcribeMelody } from "@hum2music/audio-analysis";
+import { analyzeHarmony, type TimedNote } from "@hum2music/harmony";
+
+export async function runAnalyze(args: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      chords: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+      bpm: { type: "string" },
+    },
+    allowPositionals: true,
+  });
+
+  const inputPath = positionals[0];
+  if (!inputPath) {
+    console.error("Usage: hum2music analyze <input.wav> [--chords] [--json] [--bpm <number>]");
+    process.exit(1);
+  }
+
+  const overrideBpm = values.bpm ? Number(values.bpm) : undefined;
+
+  const buffer = await Bun.file(inputPath).arrayBuffer();
+  const { sampleRate, samples } = decodeWav(buffer);
+  const transcribedNotes = transcribeMelody(samples, sampleRate);
+
+  if (transcribedNotes.length === 0) {
+    console.error("No valid pitch could be detected in the input audio.");
+    process.exit(1);
+  }
+
+  const timedNotes: TimedNote[] = transcribedNotes.map((note) => ({
+    pitch: note.midiPitch,
+    startMs: note.startMs,
+    durationMs: note.durationMs,
+    velocity: note.velocity,
+  }));
+
+  const analysis = analyzeHarmony(timedNotes, overrideBpm);
+
+  if (values.json) {
+    console.log(
+      JSON.stringify(
+        {
+          tempoCandidates: analysis.tempoCandidates,
+          selectedBpm: analysis.selectedBpm,
+          keyCandidates: analysis.keyCandidates,
+          melody: analysis.melody,
+          chords: values.chords ? analysis.chords : undefined,
+          songSections: values.chords ? analysis.songSections : undefined,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  console.log(`Tempo candidates: ${formatTempoCandidates(analysis.tempoCandidates)}`);
+  console.log(`Selected BPM: ${analysis.selectedBpm}`);
+  console.log(`Key candidates: ${formatKeyCandidates(analysis.keyCandidates)}`);
+
+  if (values.chords) {
+    console.log("Chord progression:");
+    for (const chord of analysis.chords) {
+      console.log(
+        `  bar @ beat ${chord.startBeat}: ${chord.symbol} (confidence ${chord.confidence.toFixed(2)})`,
+      );
+    }
+    console.log(`Song structure: ${formatSongSections(analysis.songSections)}`);
+  }
+}
+
+function formatSongSections(sections: ReturnType<typeof analyzeHarmony>["songSections"]): string {
+  return sections.map((s) => s.label).join("") || "(none)";
+}
+
+function formatTempoCandidates(candidates: ReturnType<typeof analyzeHarmony>["tempoCandidates"]): string {
+  return candidates.map((c) => `${c.bpm} BPM (${(c.confidence * 100).toFixed(0)}%)`).join(", ");
+}
+
+function formatKeyCandidates(candidates: ReturnType<typeof analyzeHarmony>["keyCandidates"]): string {
+  return candidates
+    .slice(0, 3)
+    .map((c) => `${c.tonic} ${c.mode} (${(c.confidence * 100).toFixed(0)}%)`)
+    .join(", ");
+}

package/src/commands/generate.ts

@@ -0,0 +1,131 @@
+import { parseArgs } from "node:util";
+import {
+  ARRANGEABLE_INSTRUMENTS,
+  composeTracks,
+  type ArrangeableInstrument,
+  type ComposedTrack,
+} from "@hum2music/arrangement";
+import { decodeWav, encodeWavPcm16, midiNoteToFrequency, transcribeMelody } from "@hum2music/audio-analysis";
+import { analyzeHarmony, type TimedNote } from "@hum2music/harmony";
+import { noteEventsToMidiNotes, writeMultiTrackMidiFile, type MidiNoteEvent, type MidiTrack } from "@hum2music/midi";
+import {
+  classifyDrumNote,
+  renderToSamples,
+  type DrumRenderNote,
+  type PitchedRenderNote,
+  type Timbre,
+} from "@hum2music/rendering";
+
+const DEFAULT_SEED = 42;
+
+export async function runGenerate(args: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      output: { type: "string", short: "o" },
+      wav: { type: "string" },
+      instruments: { type: "string" },
+      humanize: { type: "string" },
+      seed: { type: "string" },
+      bpm: { type: "string" },
+      style: { type: "string" },
+      "song-structure": { type: "boolean", default: false },
+    },
+    allowPositionals: true,
+  });
+
+  const inputPath = positionals[0];
+  const outputPath = values.output;
+  if (!inputPath || !outputPath) {
+    console.error(
+      "Usage: hum2music generate <input.wav> -o <song.mid> [--wav <song.wav>] [--instruments piano,bass,drums,guitar] [--style pop|ballad] [--song-structure] [--humanize <0-1>] [--seed <number>] [--bpm <number>]",
+    );
+    process.exit(1);
+  }
+
+  const buffer = await Bun.file(inputPath).arrayBuffer();
+  const { sampleRate, samples } = decodeWav(buffer);
+  const transcribedNotes = transcribeMelody(samples, sampleRate);
+
+  if (transcribedNotes.length === 0) {
+    console.error("No valid pitch could be detected in the input audio.");
+    process.exit(1);
+  }
+
+  const timedNotes: TimedNote[] = transcribedNotes.map((note) => ({
+    pitch: note.midiPitch,
+    startMs: note.startMs,
+    durationMs: note.durationMs,
+    velocity: note.velocity,
+  }));
+
+  const overrideBpm = values.bpm !== undefined ? Number(values.bpm) : undefined;
+  const { melody, chords, songSections, selectedBpm } = analyzeHarmony(timedNotes, { overrideBpm });
+
+  const seed = values.seed !== undefined ? Number(values.seed) : DEFAULT_SEED;
+  const tracks = composeTracks({
+    melody,
+    chords,
+    instruments: parseInstruments(values.instruments),
+    humanizeAmount: values.humanize !== undefined ? Number(values.humanize) : 0,
+    seed,
+    bpm: selectedBpm,
+    style: values.style,
+    songSections: values["song-structure"] ? songSections : undefined,
+  });
+
+  const midiTracks: MidiTrack[] = tracks.map((track) => ({
+    notes: noteEventsToMidiNotes(track.notes, selectedBpm),
+    channel: track.channel,
+    programNumber: track.programNumber,
+  }));
+  const midiBytes = writeMultiTrackMidiFile(midiTracks, { bpm: selectedBpm });
+  await Bun.write(outputPath, midiBytes);
+  console.log(`Wrote ${midiTracks.length} track(s) to ${outputPath}`);
+
+  if (values.wav) {
+    const wavBytes = renderTracksToWav(tracks, selectedBpm, seed);
+    await Bun.write(values.wav, wavBytes);
+    console.log(`Wrote WAV preview to ${values.wav}`);
+  }
+}
+
+function parseInstruments(raw: string | undefined): ArrangeableInstrument[] {
+  if (raw === undefined) return [...ARRANGEABLE_INSTRUMENTS];
+  return raw
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value): value is ArrangeableInstrument => (ARRANGEABLE_INSTRUMENTS as readonly string[]).includes(value));
+}
+
+function renderTracksToWav(tracks: ComposedTrack[], bpm: number, seed: number): ArrayBuffer {
+  const pitchedNotes: PitchedRenderNote[] = [];
+  const drumNotes: DrumRenderNote[] = [];
+
+  for (const track of tracks) {
+    const midiNotes: MidiNoteEvent[] = noteEventsToMidiNotes(track.notes, bpm);
+    if (track.instrument === "drums") {
+      for (const note of midiNotes) {
+        drumNotes.push({
+          startMs: note.startMs,
+          durationMs: note.durationMs,
+          velocity: note.velocity,
+          drumType: classifyDrumNote(note.pitch),
+        });
+      }
+    } else {
+      const timbre = track.instrument as Timbre;
+      for (const note of midiNotes) {
+        pitchedNotes.push({
+          startMs: note.startMs,
+          durationMs: note.durationMs,
+          velocity: note.velocity,
+          frequencyHz: midiNoteToFrequency(note.pitch),
+          timbre,
+        });
+      }
+    }
+  }
+
+  return encodeWavPcm16(renderToSamples(pitchedNotes, drumNotes, { seed }), 44100);
+}

package/src/commands/serve.ts

@@ -0,0 +1,17 @@
+import { parseArgs } from "node:util";
+import { startServer } from "@hum2music/web";
+
+const DEFAULT_PORT = 3000;
+
+export async function runServe(args: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args,
+    options: {
+      port: { type: "string" },
+    },
+  });
+
+  const port = values.port !== undefined ? Number(values.port) : DEFAULT_PORT;
+  startServer(port);
+  console.log(`hum2music UI available at http://localhost:${port}`);
+}

package/src/commands/transcribe.ts

@@ -0,0 +1,70 @@
+import { parseArgs } from "node:util";
+import { decodeWav, transcribeMelody } from "@hum2music/audio-analysis";
+import { analyzeHarmony, type TimedNote } from "@hum2music/harmony";
+import { humanizeMelody } from "@hum2music/expression";
+import { noteEventsToMidiNotes, writeStandardMidiFile } from "@hum2music/midi";
+
+const DEFAULT_SEED = 42;
+
+export async function runTranscribe(args: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      output: { type: "string", short: "o" },
+      humanize: { type: "string" },
+      seed: { type: "string" },
+    },
+    allowPositionals: true,
+  });
+
+  const inputPath = positionals[0];
+  const outputPath = values.output;
+
+  if (!inputPath || !outputPath) {
+    console.error("Usage: hum2music transcribe <input.wav> -o <output.mid> [--humanize <0-1>] [--seed <number>]");
+    process.exit(1);
+  }
+
+  const buffer = await Bun.file(inputPath).arrayBuffer();
+  const { sampleRate, samples } = decodeWav(buffer);
+  const transcribedNotes = transcribeMelody(samples, sampleRate);
+
+  if (transcribedNotes.length === 0) {
+    console.error("No valid pitch could be detected in the input audio.");
+    process.exit(1);
+  }
+
+  const midiBytes =
+    values.humanize !== undefined
+      ? buildHumanizedMidi(transcribedNotes, Number(values.humanize), values.seed !== undefined ? Number(values.seed) : DEFAULT_SEED)
+      : writeStandardMidiFile(
+          transcribedNotes.map((note) => ({
+            pitch: note.midiPitch,
+            startMs: note.startMs,
+            durationMs: note.durationMs,
+            velocity: note.velocity,
+          })),
+        );
+
+  await Bun.write(outputPath, midiBytes);
+  console.log(`Wrote ${transcribedNotes.length} note(s) to ${outputPath}`);
+}
+
+function buildHumanizedMidi(
+  transcribedNotes: ReturnType<typeof transcribeMelody>,
+  humanizeAmount: number,
+  seed: number,
+): Uint8Array {
+  const timedNotes: TimedNote[] = transcribedNotes.map((note) => ({
+    pitch: note.midiPitch,
+    startMs: note.startMs,
+    durationMs: note.durationMs,
+    velocity: note.velocity,
+  }));
+
+  const { melody, selectedBpm } = analyzeHarmony(timedNotes);
+  const humanized = humanizeMelody(melody, { seed, humanizeAmount, bpm: selectedBpm, instrument: "melody" });
+  const midiNotes = noteEventsToMidiNotes(humanized, selectedBpm);
+
+  return writeStandardMidiFile(midiNotes, { bpm: selectedBpm });
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+import { runAnalyze } from "./commands/analyze";
+import { runGenerate } from "./commands/generate";
+import { runServe } from "./commands/serve";
+import { runTranscribe } from "./commands/transcribe";
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+
+  switch (command) {
+    case "transcribe":
+      await runTranscribe(rest);
+      return;
+    case "analyze":
+      await runAnalyze(rest);
+      return;
+    case "generate":
+      await runGenerate(rest);
+      return;
+    case "serve":
+      await runServe(rest);
+      return;
+    default:
+      console.error(`Unknown command: ${command ?? "(none)"}`);
+      console.error("Usage: hum2music transcribe <input.wav> -o <output.mid>");
+      process.exit(1);
+  }
+}
+
+main();