@hraness/dawg 0.2.0 → 0.4.0

package/src/media/wavetable.ts

@@ -0,0 +1,202 @@
+/**
+ * `make_wavetable(file, name, {...})`: turns any audio file in the project
+ * (a download, a stem, an imported sample) into a wavetable at
+ * `tracks/<slug>/wavetables/<name>.wav` — float32 frames of 2048 samples
+ * with a `clm ` chunk, the format Serum, Vital and uzu-wavetables use — and
+ * reports how the timbre moves across it so the model can pick a position.
+ *
+ * WAV inputs are read directly; anything else goes through ffmpeg to
+ * 48 kHz mono float. The extraction itself is `src/audio/wavetable-maker.ts`.
+ */
+import { rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { SCORE_LIMITS } from "../../core/score.ts";
+import {
+  MAKE_FRAME_SIZE,
+  WavetableMakeError,
+  encodeWavetableWav,
+  makeWavetable,
+  type MakeMethod,
+  type MakeNormalize,
+} from "../audio/wavetable-maker.ts";
+import { missingTool } from "./backend.ts";
+import {
+  ensureDir,
+  formatBytes,
+  projectPath,
+  resolveInput,
+  sha256File,
+} from "./paths.ts";
+import { MediaToolError, runHelper } from "./process.ts";
+import {
+  MEDIA_LIMITS,
+  type MediaHost,
+  type MediaResult,
+  type MediaRunContext,
+} from "./types.ts";
+import { parseWav } from "./vendor/wav.ts";
+
+/** Longest source read; the maker only analyses a bounded region of it. */
+const MAX_SOURCE_SECONDS = 10 * 60;
+const DECODE_RATE = 48_000;
+
+export type MakeWavetableArgs = Readonly<{
+  file: string;
+  name: string;
+  frames?: number;
+  start?: number;
+  end?: number;
+  method?: MakeMethod;
+  smooth?: number;
+  normalize?: MakeNormalize;
+}>;
+
+export function wavetablesDir(
+  host: Pick<MediaHost, "projectRoot" | "trackSlug">,
+): string {
+  return join(host.projectRoot, "tracks", host.trackSlug, "wavetables");
+}
+
+function mixdown(
+  wav: ReturnType<typeof parseWav>,
+  maxFrames: number,
+): Float32Array {
+  const frames = Math.min(wav.sampleCount, maxFrames);
+  const out = new Float32Array(frames);
+  for (let i = 0; i < frames; i += 1) {
+    let sum = 0;
+    for (let c = 0; c < wav.channels; c += 1) sum += wav.sample(i, c);
+    out[i] = sum / wav.channels;
+  }
+  return out;
+}
+
+async function readSource(
+  context: MediaRunContext,
+  absolute: string,
+  size: number,
+): Promise<{ mono: Float32Array; sampleRate: number }> {
+  const options = {
+    maximumBytes: 2 ** 31,
+    maximumDurationSeconds: 24 * 3600,
+    maximumChannels: 32,
+  };
+  if (/\.wav$/i.test(absolute) && size <= MEDIA_LIMITS.downloadMaxBytes) {
+    try {
+      const wav = parseWav(
+        new Uint8Array(await Bun.file(absolute).arrayBuffer()),
+        options,
+      );
+      return {
+        mono: mixdown(wav, MAX_SOURCE_SECONDS * wav.sampleRate),
+        sampleRate: wav.sampleRate,
+      };
+    } catch {
+      // Unusual WAV (ADPCM, extensible quirks): let ffmpeg read it.
+    }
+  }
+  if (!context.runner.which("ffmpeg"))
+    throw new MediaToolError(missingTool("ffmpeg"));
+  const temp = join(
+    await ensureDir(wavetablesDir(context)),
+    `.decode-${process.pid}-${Date.now()}.part.wav`,
+  );
+  context.progress("ffmpeg → mono 48 kHz");
+  try {
+    await runHelper(
+      context,
+      [
+        "ffmpeg",
+        "-hide_banner",
+        "-nostdin",
+        "-loglevel",
+        "error",
+        "-y",
+        "-i",
+        absolute,
+        "-vn",
+        "-t",
+        String(MAX_SOURCE_SECONDS),
+        "-ar",
+        String(DECODE_RATE),
+        "-ac",
+        "1",
+        "-c:a",
+        "pcm_f32le",
+        temp,
+      ],
+      { timeoutMs: MEDIA_LIMITS.sampleTimeoutMs },
+    );
+    const wav = parseWav(
+      new Uint8Array(await Bun.file(temp).arrayBuffer()),
+      options,
+    );
+    return { mono: mixdown(wav, wav.sampleCount), sampleRate: wav.sampleRate };
+  } finally {
+    await Bun.file(temp)
+      .delete()
+      .catch(() => undefined);
+  }
+}
+
+export async function makeWavetableFile(
+  args: MakeWavetableArgs,
+  context: MediaRunContext,
+): Promise<MediaResult> {
+  const input = await resolveInput(context, args.file);
+  const { mono, sampleRate } = await readSource(
+    context,
+    input.absolute,
+    input.size,
+  );
+  context.progress(`analysing ${input.relative}`);
+  let made;
+  try {
+    made = makeWavetable(mono, sampleRate, {
+      ...(args.frames !== undefined ? { frames: args.frames } : {}),
+      ...(args.start !== undefined ? { start: args.start } : {}),
+      ...(args.end !== undefined ? { end: args.end } : {}),
+      ...(args.method !== undefined ? { method: args.method } : {}),
+      ...(args.smooth !== undefined ? { smooth: args.smooth } : {}),
+      ...(args.normalize !== undefined ? { normalize: args.normalize } : {}),
+    });
+  } catch (error) {
+    if (error instanceof WavetableMakeError)
+      throw new MediaToolError(error.message);
+    throw error;
+  }
+  const bytes = encodeWavetableWav(made.frames);
+  if (bytes.byteLength > SCORE_LIMITS.maxSampleFileBytes)
+    throw new MediaToolError(
+      `${formatBytes(bytes.byteLength)} is over the sample file limit; use fewer frames`,
+    );
+  const dir = await ensureDir(wavetablesDir(context));
+  const target = join(dir, `${args.name}.wav`);
+  const temp = `${target}.part`;
+  await Bun.write(temp, bytes);
+  await rename(temp, target);
+  const sha256 = await sha256File(target);
+  const path = projectPath(context.projectRoot, target);
+  const size = (await stat(target)).size;
+  const region = `${made.region.start.toFixed(2)}–${made.region.end.toFixed(2)} s${made.region.auto ? " (auto)" : ""}`;
+  return {
+    summary: `wavetable ${args.name} · ${made.frames.length} frames · ${made.method} · ${region}`,
+    outputs: [path],
+    content: {
+      wavetable: {
+        name: args.name,
+        path,
+        sha256,
+        frames: made.frames.length,
+        frameSize: MAKE_FRAME_SIZE,
+        bytes: size,
+        source: input.relative,
+        method: made.method,
+        region: made.region,
+        ...(made.pitch ? { pitch: made.pitch } : {}),
+      },
+      sweep: made.sweep,
+      next: `set_wavetable with table "${path}" plays it on a track (wt 0..1 picks the frame; wtenv or set_automation wt sweeps it). In track.ts: instrument: wavetable("./wavetables/${args.name}.wav").`,
+    },
+  };
+}

package/src/project/check.ts

@@ -0,0 +1,80 @@
+/**
+ * `dawg check`: typecheck the project, evaluate `song.ts`, print every
+ * diagnostic as `file:line:col message`, exit 1 on any failure.
+ */
+
+import {
+  evaluateProject,
+  formatDiagnostic,
+  type Diagnostic,
+} from "../../core/sdk/eval.ts";
+import { isProject } from "./init.ts";
+import { typecheckProject } from "./typecheck.ts";
+
+export type CheckDeps = Readonly<{
+  typecheck?: typeof typecheckProject;
+  evaluate?: typeof evaluateProject;
+}>;
+
+export type CheckReport = Readonly<{
+  ok: boolean;
+  diagnostics: readonly Diagnostic[];
+  typesMs: number;
+  evalMs: number;
+  tracks: number;
+  notes: number;
+}>;
+
+/** Runs both checks on `project`; never throws for project problems. */
+export async function checkProject(
+  project: string,
+  deps: CheckDeps = {},
+): Promise<CheckReport> {
+  const [types, evaluated] = await Promise.all([
+    (deps.typecheck ?? typecheckProject)(project),
+    (deps.evaluate ?? evaluateProject)(project),
+  ]);
+  const diagnostics = [
+    ...types.diagnostics,
+    ...(evaluated.ok ? [] : evaluated.diagnostics),
+  ];
+  return Object.freeze({
+    ok: types.ok && evaluated.ok,
+    diagnostics: Object.freeze(diagnostics),
+    typesMs: types.ms,
+    evalMs: evaluated.ms,
+    tracks: evaluated.ok ? evaluated.score.tracks.length : 0,
+    notes: evaluated.ok ? evaluated.score.notes.length : 0,
+  });
+}
+
+export async function runCheckCommand(
+  argv: readonly string[],
+  cwd: string,
+  stdout: { write(text: string): unknown },
+  stderr: { write(text: string): unknown },
+  deps: CheckDeps = {},
+): Promise<number> {
+  const project = cwd;
+  if (!(await isProject(project))) {
+    stderr.write(
+      "not a dawg project (no dawg.json here); run `dawg init` first\n",
+    );
+    return 1;
+  }
+  const report = await checkProject(project, deps);
+  for (const diagnostic of report.diagnostics)
+    stderr.write(`${formatDiagnostic(diagnostic)}\n`);
+  if (report.ok) {
+    stdout.write(
+      `ok · ${report.tracks} track${report.tracks === 1 ? "" : "s"}, ${report.notes} note${
+        report.notes === 1 ? "" : "s"
+      } · types ${report.typesMs} ms · eval ${report.evalMs} ms\n`,
+    );
+    return 0;
+  }
+  const count = report.diagnostics.length;
+  stderr.write(`${count} problem${count === 1 ? "" : "s"}\n`);
+  void argv;
+  return 1;
+}

package/src/project/init.ts

@@ -0,0 +1,253 @@
+/**
+ * Project layout on disk:
+ *
+ *   dawg.json              project marker: format and SDK major
+ *   tsconfig.json          strict, `"dawg"` → `.dawg/sdk/v1.ts`
+ *   song.ts                `export default song({ ..., tracks: [...] })`
+ *   tracks/<slug>/track.ts one `track({...})` per track (+ `samples/`)
+ *   .dawg/sdk/v1.ts        vendored SDK, refreshed when the shipped copy is newer
+ *   .dawg/sdk/tsconfig.json compiler options the root config extends
+ *   .dawg/tsbuild/         incremental typecheck state
+ *   .dawg/sync.json        hashes of files dawg wrote (echo suppression)
+ *
+ * `initProject` is idempotent, writes only under `dir`, and reports each
+ * file it created or refreshed exactly once.
+ */
+
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PROJECT_FILE = "dawg.json";
+export const PROJECT_FORMAT = "dawg.project/v1";
+export const SDK_RELATIVE_PATH = ".dawg/sdk/v1.ts";
+export const SDK_TSCONFIG_RELATIVE_PATH = ".dawg/sdk/tsconfig.json";
+
+/** The SDK source dawg ships (`core/sdk/v1.ts`). */
+export const SHIPPED_SDK_PATH = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+  "core",
+  "sdk",
+  "v1.ts",
+);
+
+export type ProjectManifest = Readonly<{ format: string; sdk: number }>;
+
+export type InitResult = Readonly<{
+  /** Project-relative paths created or refreshed, in write order. */
+  wrote: readonly string[];
+  /** SDK version now vendored in the project. */
+  sdkVersion: string;
+}>;
+
+const SDK_TSCONFIG = `${JSON.stringify(
+  {
+    compilerOptions: {
+      target: "ES2022",
+      module: "ESNext",
+      moduleResolution: "Bundler",
+      strict: true,
+      noUncheckedIndexedAccess: true,
+      noEmit: true,
+      skipLibCheck: true,
+      allowImportingTsExtensions: true,
+      types: [],
+    },
+  },
+  null,
+  2,
+)}\n`;
+
+const ROOT_TSCONFIG = `${JSON.stringify(
+  {
+    extends: "./.dawg/sdk/tsconfig.json",
+    compilerOptions: { paths: { dawg: ["./.dawg/sdk/v1.ts"] } },
+    include: ["song.ts", "tracks/**/*.ts", ".dawg/sdk/*.ts"],
+  },
+  null,
+  2,
+)}\n`;
+
+const EMPTY_SONG = `import { song } from "dawg";
+
+export default song({
+  tempo: 120,
+  meter: [4, 4],
+  bars: 4,
+  tracks: [],
+});
+`;
+
+const GITIGNORE_LINES = [".dawg/*", "!.dawg/sdk/"];
+
+/** True when `dir` holds a `dawg.json`. */
+export async function isProject(dir: string): Promise<boolean> {
+  return (await readManifest(dir)) !== undefined;
+}
+
+/** Parses `dawg.json` from unknown; undefined when absent or unreadable. */
+export async function readManifest(
+  dir: string,
+): Promise<ProjectManifest | undefined> {
+  let text: string;
+  try {
+    text = await readFile(join(dir, PROJECT_FILE), "utf8");
+  } catch {
+    return undefined;
+  }
+  if (text.length > 4096) return undefined;
+  try {
+    const value: unknown = JSON.parse(text);
+    if (typeof value !== "object" || value === null) return undefined;
+    const record = value as Record<string, unknown>;
+    if (record.format !== PROJECT_FORMAT) return undefined;
+    if (typeof record.sdk !== "number" || !Number.isInteger(record.sdk))
+      return undefined;
+    return Object.freeze({ format: PROJECT_FORMAT, sdk: record.sdk });
+  } catch {
+    return undefined;
+  }
+}
+
+/** Version string declared by an SDK source file, or undefined. */
+export function sdkVersionOf(source: string): string | undefined {
+  const match = source.match(/SDK_VERSION = "(\d+)\.(\d+)\.(\d+)"/);
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : undefined;
+}
+
+function newer(candidate: string, current: string | undefined): boolean {
+  if (current === undefined) return true;
+  const a = candidate.split(".").map(Number);
+  const b = current.split(".").map(Number);
+  if (a[0] !== b[0]) return false; // a different major is never auto-applied
+  for (let index = 1; index < 3; index += 1)
+    if (a[index]! !== b[index]!) return a[index]! > b[index]!;
+  return false;
+}
+
+export type InitOptions = Readonly<{
+  /** SDK source to vendor; defaults to the shipped `core/sdk/v1.ts`. */
+  sdkSource?: string;
+}>;
+
+/**
+ * Creates or refreshes the project in `dir`. Existing `song.ts`,
+ * `tsconfig.json`, `.gitignore` entries and `dawg.json` are left alone;
+ * the vendored SDK is replaced only by a newer copy of the same major.
+ */
+export async function initProject(
+  dir: string,
+  options: InitOptions = {},
+): Promise<InitResult> {
+  const wrote: string[] = [];
+  const sdkSource =
+    options.sdkSource ?? (await readFile(SHIPPED_SDK_PATH, "utf8"));
+  const shippedVersion = sdkVersionOf(sdkSource);
+  if (!shippedVersion) throw new Error("shipped SDK has no SDK_VERSION");
+  const major = Number(shippedVersion.split(".")[0]);
+
+  await mkdir(join(dir, ".dawg", "sdk"), { recursive: true });
+  await mkdir(join(dir, "tracks"), { recursive: true });
+
+  const vendored = await readOptional(join(dir, SDK_RELATIVE_PATH));
+  const vendoredVersion =
+    vendored === undefined ? undefined : sdkVersionOf(vendored);
+  let sdkVersion = vendoredVersion ?? shippedVersion;
+  if (vendored === undefined || newer(shippedVersion, vendoredVersion)) {
+    await writeAtomic(join(dir, SDK_RELATIVE_PATH), sdkSource);
+    wrote.push(SDK_RELATIVE_PATH);
+    sdkVersion = shippedVersion;
+  }
+  if (
+    (await readOptional(join(dir, SDK_TSCONFIG_RELATIVE_PATH))) !== SDK_TSCONFIG
+  ) {
+    await writeAtomic(join(dir, SDK_TSCONFIG_RELATIVE_PATH), SDK_TSCONFIG);
+    wrote.push(SDK_TSCONFIG_RELATIVE_PATH);
+  }
+  if ((await readManifest(dir)) === undefined) {
+    await writeAtomic(
+      join(dir, PROJECT_FILE),
+      `${JSON.stringify({ format: PROJECT_FORMAT, sdk: major }, null, 2)}\n`,
+    );
+    wrote.push(PROJECT_FILE);
+  }
+  if ((await readOptional(join(dir, "tsconfig.json"))) === undefined) {
+    await writeAtomic(join(dir, "tsconfig.json"), ROOT_TSCONFIG);
+    wrote.push("tsconfig.json");
+  }
+  if ((await readOptional(join(dir, "song.ts"))) === undefined) {
+    await writeAtomic(join(dir, "song.ts"), EMPTY_SONG);
+    // Recorded as dawg-written so the first window lets the session win.
+    await writeAtomic(
+      join(dir, ".dawg", "sync.json"),
+      `${JSON.stringify(
+        {
+          files: {
+            "song.ts": createHash("sha256").update(EMPTY_SONG).digest("hex"),
+          },
+        },
+        null,
+        2,
+      )}\n`,
+    );
+    wrote.push("song.ts");
+  }
+  const gitignore = (await readOptional(join(dir, ".gitignore"))) ?? "";
+  const present = new Set(gitignore.split("\n").map((line) => line.trim()));
+  const missing = GITIGNORE_LINES.filter((line) => !present.has(line));
+  if (missing.length > 0) {
+    const prefix =
+      gitignore.length === 0 || gitignore.endsWith("\n") ? "" : "\n";
+    await writeAtomic(
+      join(dir, ".gitignore"),
+      `${gitignore}${prefix}${missing.join("\n")}\n`,
+    );
+    wrote.push(".gitignore");
+  }
+  return Object.freeze({ wrote: Object.freeze(wrote), sdkVersion });
+}
+
+/** `dawg init [dir]`: creates the project and prints what it wrote. */
+export async function runInitCommand(
+  argv: readonly string[],
+  cwd: string,
+  stdout: { write(text: string): unknown },
+  stderr: { write(text: string): unknown },
+): Promise<number> {
+  const target =
+    argv[1] && !argv[1].startsWith("--") ? resolve(cwd, argv[1]) : cwd;
+  try {
+    const result = await initProject(target);
+    if (result.wrote.length === 0)
+      stdout.write(`project up to date (sdk ${result.sdkVersion})\n`);
+    else for (const path of result.wrote) stdout.write(`wrote ${path}\n`);
+    return 0;
+  } catch (error) {
+    stderr.write(
+      `init failed: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return 1;
+  }
+}
+
+async function readOptional(path: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Temp file + rename so a reader never sees a partial file. */
+export async function writeAtomic(
+  path: string,
+  contents: string,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, contents, "utf8");
+  await rename(temporary, path);
+}