@hraness/dawg 0.2.0 → 0.4.0

package/src/media/vendor/grid.ts

@@ -0,0 +1,203 @@
+// Vendored from soundfish `lib/song-import/grid.ts` (same owner); the protocol constants it imported are local here.
+import type { BeatGrid } from "../types.ts";
+import { clamp, finiteNumber, isRecord, parseJson } from "./util.ts";
+
+const MAX_BEATS = 20_000;
+const MAX_DURATION_SECONDS = 7_200;
+export const FIXED_GRID_DETECTOR = "dawg-fixed-grid";
+
+/** Validates a StemDeck `/api/jobs/<id>/beats` body from `unknown`. */
+export function parseBeatGrid(bytes: Uint8Array): BeatGrid {
+  const value = parseJson(bytes, "StemDeck beat grid");
+  if (!isRecord(value) || !Array.isArray(value.beats)) {
+    throw new Error("StemDeck beat grid did not contain a beats array.");
+  }
+  if (value.beats.length < 2 || value.beats.length > MAX_BEATS) {
+    throw new Error(`StemDeck beat grid must contain 2–${MAX_BEATS} beats.`);
+  }
+  const beats = value.beats.map((entry, index) => {
+    const beat = finiteNumber(entry);
+    if (beat === undefined || beat < 0 || beat > MAX_DURATION_SECONDS) {
+      throw new Error(
+        `StemDeck beat ${index} is outside the supported time range.`,
+      );
+    }
+    return beat;
+  });
+  for (let index = 1; index < beats.length; index += 1) {
+    if (beats[index]! <= beats[index - 1]!) {
+      throw new Error("StemDeck beat times must be strictly increasing.");
+    }
+  }
+  const duration = finiteNumber(value.duration);
+  const lastBeat = beats.at(-1)!;
+  const fallbackDuration = Math.min(
+    MAX_DURATION_SECONDS,
+    lastBeat + (lastBeat - beats.at(-2)!),
+  );
+  const durationSeconds =
+    duration === undefined
+      ? fallbackDuration
+      : clamp(duration, lastBeat, MAX_DURATION_SECONDS);
+  const bars = Array.isArray(value.bars)
+    ? value.bars.slice(0, 2_000).flatMap((entry) => {
+        if (!isRecord(entry)) return [];
+        const beat = finiteNumber(entry.beat);
+        const beatsPerBar = finiteNumber(
+          entry.beats_per_bar ?? entry.beatsPerBar,
+        );
+        if (
+          beat === undefined ||
+          beatsPerBar === undefined ||
+          !Number.isSafeInteger(beat) ||
+          !Number.isSafeInteger(beatsPerBar) ||
+          beat < 0 ||
+          beat >= beats.length ||
+          beatsPerBar < 1 ||
+          beatsPerBar > 32
+        ) {
+          return [];
+        }
+        return [{ beat, beatsPerBar }];
+      })
+    : [];
+  const bpm = finiteNumber(value.bpm);
+  const confidence = finiteNumber(value.confidence);
+  const intervalCv = finiteNumber(value.interval_cv);
+  return {
+    beats,
+    bars,
+    durationSeconds,
+    ...(bpm === undefined ? {} : { bpm }),
+    ...(typeof value.detector === "string"
+      ? { detector: value.detector.slice(0, 80) }
+      : {}),
+    ...(confidence === undefined
+      ? {}
+      : { confidence: clamp(confidence, 0, 100) }),
+    intervalCv:
+      intervalCv === undefined
+        ? beatIntervalCv(beats)
+        : clamp(intervalCv, 0, 10),
+  };
+}
+
+export function beatIntervalCv(beats: readonly number[]): number {
+  if (beats.length < 3) return 0;
+  const intervals = beats
+    .slice(1)
+    .map((beat, index) => beat - beats[index]!)
+    .filter((value) => value > 0);
+  if (intervals.length < 2) return 0;
+  const mean =
+    intervals.reduce((sum, value) => sum + value, 0) / intervals.length;
+  const variance =
+    intervals.reduce((sum, value) => sum + (value - mean) ** 2, 0) /
+    intervals.length;
+  return mean <= 0 ? 0 : Math.sqrt(variance) / mean;
+}
+
+function edgeInterval(beats: readonly number[], atEnd: boolean): number {
+  const count = Math.min(8, beats.length - 1);
+  let sum = 0;
+  for (let offset = 0; offset < count; offset += 1) {
+    const index = atEnd ? beats.length - 2 - offset : offset;
+    sum += beats[index + 1]! - beats[index]!;
+  }
+  return sum / count;
+}
+
+/** Piecewise-linear source seconds to the global beat axis (beat 0 = first beat). */
+export function secondsToBeat(
+  grid: Pick<BeatGrid, "beats">,
+  seconds: number,
+): number {
+  const beats = grid.beats;
+  if (beats.length < 2 || !Number.isFinite(seconds)) {
+    throw new Error("Cannot map time without a valid beat grid.");
+  }
+  if (seconds <= beats[0]!) {
+    return (seconds - beats[0]!) / edgeInterval(beats, false);
+  }
+  const lastIndex = beats.length - 1;
+  if (seconds >= beats[lastIndex]!) {
+    return (
+      lastIndex + (seconds - beats[lastIndex]!) / edgeInterval(beats, true)
+    );
+  }
+  let low = 0;
+  let high = lastIndex;
+  while (low + 1 < high) {
+    const middle = Math.floor((low + high) / 2);
+    if (beats[middle]! <= seconds) low = middle;
+    else high = middle;
+  }
+  const interval = beats[low + 1]! - beats[low]!;
+  return low + (seconds - beats[low]!) / interval;
+}
+
+/** Inverse of secondsToBeat on the same piecewise-linear beat axis. */
+export function beatToSeconds(
+  grid: Pick<BeatGrid, "beats">,
+  beat: number,
+): number {
+  const beats = grid.beats;
+  if (beats.length < 2 || !Number.isFinite(beat)) {
+    throw new Error("Cannot map beats without a valid beat grid.");
+  }
+  const lastIndex = beats.length - 1;
+  if (beat <= 0) return beats[0]! + beat * edgeInterval(beats, false);
+  if (beat >= lastIndex) {
+    return beats[lastIndex]! + (beat - lastIndex) * edgeInterval(beats, true);
+  }
+  const index = Math.floor(beat);
+  const fraction = beat - index;
+  return beats[index]! + fraction * (beats[index + 1]! - beats[index]!);
+}
+
+export function gridMedianBpm(grid: Pick<BeatGrid, "beats" | "bpm">): number {
+  if (grid.bpm !== undefined && Number.isFinite(grid.bpm)) {
+    return clamp(Math.round(grid.bpm), 40, 240);
+  }
+  const intervals = grid.beats
+    .slice(1)
+    .map((beat, index) => beat - grid.beats[index]!)
+    .filter((interval) => interval > 0)
+    .sort((left, right) => left - right);
+  if (intervals.length === 0) return 120;
+  const middle = Math.floor(intervals.length / 2);
+  const median =
+    intervals.length % 2 === 0
+      ? (intervals[middle - 1]! + intervals[middle]!) / 2
+      : intervals[middle]!;
+  return clamp(Math.round(60 / median), 40, 240);
+}
+
+/** A metronomic grid at `bpm` from `offsetSeconds`, 4 beats per bar. */
+export function fixedBeatGrid(
+  bpm: number,
+  durationSeconds: number,
+  offsetSeconds = 0,
+): BeatGrid {
+  const interval = 60 / clamp(bpm, 40, 240);
+  const duration = clamp(durationSeconds, interval * 2, MAX_DURATION_SECONDS);
+  const count = Math.min(
+    MAX_BEATS,
+    Math.max(2, Math.ceil(duration / interval)),
+  );
+  const beats: number[] = [];
+  const start = clamp(offsetSeconds, 0, interval);
+  for (let index = 0; index < count; index += 1)
+    beats.push(start + index * interval);
+  const bars: { beat: number; beatsPerBar: number }[] = [];
+  for (let beat = 0; beat < count; beat += 4)
+    bars.push({ beat, beatsPerBar: 4 });
+  return {
+    beats,
+    bars,
+    durationSeconds: duration,
+    bpm,
+    detector: FIXED_GRID_DETECTOR,
+    intervalCv: 0,
+  };
+}

package/src/media/vendor/util.ts

@@ -0,0 +1,139 @@
+// Vendored from soundfish `lib/song-import/util.ts` (same owner); trimmed to what dawg's media tools use.
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+export function decodeUtf8(bytes: Uint8Array, label: string): string {
+  try {
+    return decoder.decode(bytes);
+  } catch {
+    throw new Error(`${label} was not valid UTF-8.`);
+  }
+}
+
+export function parseJson(bytes: Uint8Array, label: string): unknown {
+  const text = decodeUtf8(bytes, label);
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new Error(`${label} was not valid JSON.`);
+  }
+}
+
+export function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+export function optionalString(
+  value: unknown,
+  maximumLength = 1_000,
+): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 && trimmed.length <= maximumLength
+    ? trimmed
+    : undefined;
+}
+
+function boundedUtf8(
+  value: string,
+  maximumBytes: number,
+  fallback: string,
+): string {
+  const wellFormed = new TextDecoder().decode(new TextEncoder().encode(value));
+  const normalized = wellFormed
+    .replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+  if (!normalized) return fallback;
+  if (encoder.encode(normalized).byteLength <= maximumBytes) return normalized;
+  let result = "";
+  for (const character of normalized) {
+    if (encoder.encode(`${result}${character}`).byteLength > maximumBytes)
+      break;
+    result += character;
+  }
+  return result.trim() || fallback;
+}
+
+/** Safe for reflecting untrusted service/process text into a terminal line. */
+export function terminalSafeText(
+  value: string,
+  maximumBytes = 2_000,
+  fallback = "External tool error",
+): string {
+  return boundedUtf8(value.replace(/[‪-‮⁦-⁩]/gu, " "), maximumBytes, fallback);
+}
+
+export function clamp(value: number, minimum: number, maximum: number): number {
+  return Math.max(minimum, Math.min(maximum, value));
+}
+
+export function fileBaseName(path: string): string {
+  return path.replace(/\\/gu, "/").split("/").at(-1) ?? path;
+}
+
+/** Absolute HTTP(S) URL without credentials, query, or fragment. */
+export function normalizeServiceBaseUrl(value: string): URL {
+  if (encoder.encode(value).byteLength > 2_048) {
+    throw new Error("DAWG_STEMDECK_URL must be at most 2048 UTF-8 bytes.");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("DAWG_STEMDECK_URL must be an absolute HTTP(S) URL.");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("DAWG_STEMDECK_URL must use HTTP or HTTPS.");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error(
+      "DAWG_STEMDECK_URL cannot include credentials, a query, or a fragment.",
+    );
+  }
+  parsed.pathname = parsed.pathname.replace(/\/+$/gu, "");
+  return parsed;
+}
+
+/**
+ * Accepts YouTube hosts only and strips credentials and the fragment, so the
+ * value is safe to log and to hand to yt-dlp or StemDeck.
+ */
+export function validateYoutubeUrl(value: string): string {
+  if (value.length > 2_048) throw new Error("The YouTube URL is too long.");
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("The input must be an absolute YouTube URL.");
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error("The YouTube URL must use HTTP or HTTPS.");
+  }
+  const host = parsed.hostname.toLowerCase();
+  const accepted =
+    host === "youtu.be" ||
+    host === "youtube.com" ||
+    host.endsWith(".youtube.com") ||
+    host === "youtube-nocookie.com" ||
+    host.endsWith(".youtube-nocookie.com");
+  if (!accepted) throw new Error("The input host is not YouTube.");
+  parsed.username = "";
+  parsed.password = "";
+  parsed.hash = "";
+  return parsed.toString();
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function errorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "Unknown error";
+  }
+}

package/src/media/vendor/wav.ts

@@ -0,0 +1,233 @@
+// Vendored from soundfish `lib/audio-media/wav.ts` (same owner): RIFF/WAVE parser for PCM 16/24/32 and float32.
+
+export type WavFailureCode = "unsupported_media" | "decode_failed" | "too_long";
+
+export class WavFormatError extends Error {
+  readonly code: WavFailureCode;
+
+  constructor(code: WavFailureCode, message: string) {
+    super(message);
+    this.name = "WavFormatError";
+    this.code = code;
+  }
+}
+
+export type WavEncoding = "pcm16" | "pcm24" | "pcm32" | "float32";
+
+export type ParsedWav = Readonly<{
+  sampleRate: number;
+  channels: number;
+  /** Frame count: one frame carries one sample per channel. */
+  sampleCount: number;
+  encoding: WavEncoding;
+  sample: (frame: number, channel: number) => number;
+}>;
+
+export type ParseWavOptions = Readonly<{
+  /** Whole-buffer ceiling; larger inputs fail as `too_long`. Default 256 MiB. */
+  maximumBytes?: number;
+  /** Duration ceiling from the header; default two hours. */
+  maximumDurationSeconds?: number;
+  maximumChannels?: number;
+}>;
+
+export const WAV_DEFAULT_MAXIMUM_BYTES = 256 * 1024 * 1024;
+export const WAV_DEFAULT_MAXIMUM_DURATION_SECONDS = 7_200;
+export const WAV_DEFAULT_MAXIMUM_CHANNELS = 8;
+const WAV_MINIMUM_SAMPLE_RATE = 8_000;
+const WAV_MAXIMUM_SAMPLE_RATE = 192_000;
+
+const FORMAT_PCM = 0x0001;
+const FORMAT_IEEE_FLOAT = 0x0003;
+const FORMAT_EXTENSIBLE = 0xfffe;
+const MINIMUM_FMT_BYTES = 16;
+const EXTENSIBLE_FMT_BYTES = 40;
+const DATA_SIZE_UNKNOWN = 0xffffffff;
+/** Trailing 14 bytes of KSDATAFORMAT_SUBTYPE_PCM / _IEEE_FLOAT after the 16-bit tag. */
+const SUBFORMAT_GUID_SUFFIX = [
+  0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0xaa, 0x00, 0x38, 0x9b,
+  0x71,
+];
+
+function ascii(bytes: Uint8Array, offset: number, count: number): string {
+  return String.fromCharCode(...bytes.subarray(offset, offset + count));
+}
+
+function clampUnit(value: number): number {
+  return value < -1 ? -1 : value > 1 ? 1 : value;
+}
+
+type FormatChunk = Readonly<{
+  audioFormat: number;
+  channels: number;
+  sampleRate: number;
+  blockAlign: number;
+  bits: number;
+}>;
+
+function readFormatChunk(
+  bytes: Uint8Array,
+  view: DataView,
+  start: number,
+  size: number,
+): FormatChunk {
+  if (size < MINIMUM_FMT_BYTES)
+    throw new WavFormatError("decode_failed", "WAV has a short format chunk.");
+  let audioFormat = view.getUint16(start, true);
+  if (audioFormat === FORMAT_EXTENSIBLE) {
+    if (size < EXTENSIBLE_FMT_BYTES || view.getUint16(start + 16, true) < 22) {
+      throw new WavFormatError(
+        "unsupported_media",
+        "WAV extensible format chunk is incomplete.",
+      );
+    }
+    const subFormat = start + 24;
+    const suffixMatches = SUBFORMAT_GUID_SUFFIX.every(
+      (byte, index) => bytes[subFormat + 2 + index] === byte,
+    );
+    if (!suffixMatches)
+      throw new WavFormatError(
+        "unsupported_media",
+        "WAV SubFormat is not PCM or IEEE float.",
+      );
+    audioFormat = view.getUint16(subFormat, true);
+  }
+  return {
+    audioFormat,
+    channels: view.getUint16(start + 2, true),
+    sampleRate: view.getUint32(start + 4, true),
+    blockAlign: view.getUint16(start + 12, true),
+    bits: view.getUint16(start + 14, true),
+  };
+}
+
+function encodingFor(format: FormatChunk): WavEncoding | undefined {
+  if (format.audioFormat === FORMAT_PCM) {
+    if (format.bits === 16) return "pcm16";
+    if (format.bits === 24) return "pcm24";
+    if (format.bits === 32) return "pcm32";
+    return undefined;
+  }
+  if (format.audioFormat === FORMAT_IEEE_FLOAT && format.bits === 32)
+    return "float32";
+  return undefined;
+}
+
+export function parseWav(
+  bytes: Uint8Array,
+  options: ParseWavOptions = {},
+): ParsedWav {
+  const maximumBytes = options.maximumBytes ?? WAV_DEFAULT_MAXIMUM_BYTES;
+  const maximumDurationSeconds =
+    options.maximumDurationSeconds ?? WAV_DEFAULT_MAXIMUM_DURATION_SECONDS;
+  const maximumChannels =
+    options.maximumChannels ?? WAV_DEFAULT_MAXIMUM_CHANNELS;
+  if (bytes.byteLength < 44 || bytes.byteLength > maximumBytes) {
+    const megabytes = Math.floor(maximumBytes / (1024 * 1024));
+    throw new WavFormatError(
+      bytes.byteLength < 44 ? "decode_failed" : "too_long",
+      `WAV is missing or exceeds the ${megabytes} MiB analysis limit.`,
+    );
+  }
+  if (ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WAVE") {
+    throw new WavFormatError(
+      "unsupported_media",
+      "File is not a RIFF/WAVE file.",
+    );
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let offset = 12;
+  let format: FormatChunk | undefined;
+  let dataOffset = -1;
+  let dataBytes = 0;
+  while (offset + 8 <= bytes.byteLength) {
+    const id = ascii(bytes, offset, 4);
+    const size = view.getUint32(offset + 4, true);
+    const start = offset + 8;
+    if (id === "data" && size === DATA_SIZE_UNKNOWN) {
+      throw new WavFormatError(
+        "unsupported_media",
+        "WAV data chunk has an unknown length.",
+      );
+    }
+    const end = start + size;
+    if (end > bytes.byteLength)
+      throw new WavFormatError(
+        "decode_failed",
+        "WAV contains a truncated chunk.",
+      );
+    if (id === "fmt ") {
+      format = readFormatChunk(bytes, view, start, size);
+    } else if (id === "data" && dataOffset < 0) {
+      dataOffset = start;
+      dataBytes = size;
+    }
+    offset = end + (size & 1);
+  }
+  if (!format || dataOffset < 0)
+    throw new WavFormatError(
+      "decode_failed",
+      "WAV is missing format or audio data.",
+    );
+  if (
+    format.channels < 1 ||
+    format.channels > maximumChannels ||
+    format.sampleRate < WAV_MINIMUM_SAMPLE_RATE ||
+    format.sampleRate > WAV_MAXIMUM_SAMPLE_RATE
+  ) {
+    throw new WavFormatError(
+      "unsupported_media",
+      "WAV channel count or sample rate is unsupported.",
+    );
+  }
+  const encoding = encodingFor(format);
+  if (!encoding)
+    throw new WavFormatError(
+      "unsupported_media",
+      "WAV must be PCM16/24/32 or IEEE float32.",
+    );
+  const bytesPerSample = format.bits / 8;
+  const blockAlign = format.blockAlign;
+  if (
+    blockAlign !== bytesPerSample * format.channels ||
+    dataBytes % blockAlign !== 0
+  ) {
+    throw new WavFormatError(
+      "decode_failed",
+      "WAV has an inconsistent block alignment.",
+    );
+  }
+  const sampleCount = dataBytes / blockAlign;
+  if (sampleCount / format.sampleRate > maximumDurationSeconds) {
+    throw new WavFormatError(
+      "too_long",
+      `WAV exceeds the ${maximumDurationSeconds} second analysis limit.`,
+    );
+  }
+  const sample = (frame: number, channel: number): number => {
+    const position = dataOffset + frame * blockAlign + channel * bytesPerSample;
+    switch (encoding) {
+      case "float32":
+        return clampUnit(view.getFloat32(position, true));
+      case "pcm16":
+        return view.getInt16(position, true) / 32_768;
+      case "pcm24": {
+        let value =
+          view.getUint8(position) |
+          (view.getUint8(position + 1) << 8) |
+          (view.getUint8(position + 2) << 16);
+        if (value & 0x800000) value |= 0xff000000;
+        return value / 8_388_608;
+      }
+      case "pcm32":
+        return view.getInt32(position, true) / 2_147_483_648;
+    }
+  };
+  return {
+    sampleRate: format.sampleRate,
+    channels: format.channels,
+    sampleCount,
+    encoding,
+    sample,
+  };
+}