@hraness/dawg 0.6.1 → 0.8.0

package/src/audio/audio-command.ts

@@ -0,0 +1,218 @@
+/**
+ * `audio`, `audio out <name|default>`, `audio in <name|default>` and
+ * `audio test`: the typed form of Ctrl-K › Project › audio. One output and
+ * one input; the choice lives in `<config>/audio.json` on this machine.
+ */
+import type { AudioBackendInfo } from "./engine.ts";
+import {
+  audioChoicePath,
+  blipSamples,
+  deviceLabel,
+  deviceSupport,
+  levelMeter,
+  listDevices,
+  matchDevice,
+  measureInput,
+  parseAudioCommand,
+  playOnce,
+  readAudioChoice,
+  writeAudioChoice,
+  type AudioChoice,
+} from "./devices.ts";
+import type { MenuAudioDevices } from "../tui/menu.ts";
+
+export const AUDIO_USAGE =
+  "usage · audio · audio out <name|default> · audio in <name|default> · audio test";
+
+export type AudioCommandContext = Readonly<{
+  info: AudioBackendInfo;
+  env?: Readonly<Record<string, string | undefined>>;
+  /** Where the choice is saved (default `<config>/audio.json`). */
+  path?: string;
+  /** Move this window's playback (the engine's `setDevice`). */
+  setOutput?: (name: string | undefined) => void;
+  /** Injected by tests: no real waiting for the blip, tone and meter. */
+  wait?: (ms: number) => Promise<void>;
+  /** Run the blip without blocking the reply (the default awaits it). */
+  background?: (task: Promise<unknown>) => void;
+}>;
+
+export type AudioCommandResult = Readonly<{
+  ok: boolean;
+  message: string;
+  /** Extra lines for a panel (the device lists, the test result). */
+  lines?: readonly string[];
+}>;
+
+function names(devices: readonly { name: string }[]): string {
+  return devices.length > 0
+    ? devices.map((device) => device.name).join(" · ")
+    : "none found";
+}
+
+/** What Project › audio shows. */
+export function audioMenuState(
+  info: AudioBackendInfo,
+  choice: AudioChoice = readAudioChoice(),
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): MenuAudioDevices {
+  const support = deviceSupport(info);
+  if (support.kind !== "native") {
+    const output =
+      support.kind === "sox"
+        ? ((env.DAWG_AUDIO_DEVICE?.trim() || choice.output) ?? "default")
+        : "default";
+    return {
+      output,
+      input: "default",
+      outputs: [],
+      inputs: [],
+      unavailable:
+        support.kind === "sox"
+          ? "sox cannot list devices · type audio out <name> (sox AUDIODEV) · the native sink lists them"
+          : support.reason,
+    };
+  }
+  const outputs = listDevices(support.library, false);
+  const inputs = listDevices(support.library, true);
+  const override = env.DAWG_AUDIO_DEVICE?.trim();
+  return {
+    output: deviceLabel(override || choice.output, outputs),
+    input: deviceLabel(choice.input, inputs),
+    outputs: outputs.map((device) => device.name),
+    inputs: inputs.map((device) => device.name),
+  };
+}
+
+export async function runAudioCommand(
+  args: string,
+  context: AudioCommandContext,
+): Promise<AudioCommandResult> {
+  const parsed = parseAudioCommand(args);
+  if (!parsed) return { ok: false, message: AUDIO_USAGE };
+  const env = context.env ?? process.env;
+  const path = context.path ?? audioChoicePath(env);
+  const choice = readAudioChoice(path);
+  const support = deviceSupport(context.info);
+  const override = env.DAWG_AUDIO_DEVICE?.trim() || undefined;
+  const overrideNote = override
+    ? ` · DAWG_AUDIO_DEVICE=${override} overrides the output`
+    : "";
+
+  if (parsed.kind === "show") {
+    const state = audioMenuState(context.info, choice, env);
+    const lines = [
+      `output  ${state.output}`,
+      `input   ${state.input}`,
+      `player  ${context.info.backend}`,
+    ];
+    if (state.unavailable) lines.push(state.unavailable);
+    else {
+      lines.push(`outputs ${state.outputs.join(" · ") || "none found"}`);
+      lines.push(`inputs  ${state.inputs.join(" · ") || "none found"}`);
+    }
+    return {
+      ok: true,
+      message: `audio · out ${state.output} · in ${state.input}${overrideNote}`,
+      lines,
+    };
+  }
+
+  if (support.kind === "none") return { ok: false, message: support.reason };
+
+  if (parsed.kind === "set" && parsed.side === "output") {
+    if (support.kind === "sox") {
+      writeAudioChoice("output", parsed.name, path);
+      context.setOutput?.(override ?? parsed.name);
+      return {
+        ok: true,
+        message: `audio out ${parsed.name ?? "default"} · sox plays on AUDIODEV (it cannot list devices; the native sink can)${overrideNote}`,
+      };
+    }
+    const devices = listDevices(support.library, false);
+    const device = parsed.name ? matchDevice(devices, parsed.name) : undefined;
+    if (parsed.name && !device)
+      return {
+        ok: false,
+        message: `no output named "${parsed.name}" · ${names(devices)}`,
+      };
+    writeAudioChoice("output", device?.name, path);
+    const playing = override ?? device?.name;
+    context.setOutput?.(playing);
+    // The soft blip says where sound now comes out.
+    const blip = playOnce(
+      support.library,
+      playing,
+      blipSamples(48_000),
+      48_000,
+      context.wait,
+    ).catch(() => false);
+    if (context.background) context.background(blip);
+    else await blip;
+    return {
+      ok: true,
+      message: `audio out ${deviceLabel(device?.name, devices)}${overrideNote}`,
+    };
+  }
+
+  if (parsed.kind === "set") {
+    if (support.kind === "sox")
+      return {
+        ok: false,
+        message:
+          "choosing an input needs the native sink (it captures by name; sox here only plays)",
+      };
+    const devices = listDevices(support.library, true);
+    const device = parsed.name ? matchDevice(devices, parsed.name) : undefined;
+    if (parsed.name && !device)
+      return {
+        ok: false,
+        message: `no input named "${parsed.name}" · ${names(devices)}`,
+      };
+    writeAudioChoice("input", device?.name, path);
+    return {
+      ok: true,
+      message: `audio in ${deviceLabel(device?.name, devices)} · audio test meters it`,
+    };
+  }
+
+  // audio test: a short tone on the output, then the input's level.
+  if (support.kind === "sox")
+    return {
+      ok: false,
+      message:
+        "audio test needs the native sink (it plays the tone and meters the input)",
+    };
+  const output = override ?? choice.output;
+  const outputs = listDevices(support.library, false);
+  const inputs = listDevices(support.library, true);
+  const played = await playOnce(
+    support.library,
+    output,
+    blipSamples(48_000, 0.4, 440, 0.15),
+    48_000,
+    context.wait,
+  ).catch(() => false);
+  let meter: string;
+  try {
+    const level = await measureInput(
+      support.library,
+      choice.input,
+      1,
+      48_000,
+      context.wait,
+    );
+    meter = levelMeter(level.peakDb);
+  } catch (error) {
+    meter = `could not open (${error instanceof Error ? error.message : String(error)})`;
+  }
+  const lines = [
+    `output  ${deviceLabel(output, outputs)} · ${played ? "tone played" : "could not open"}`,
+    `input   ${deviceLabel(choice.input, inputs)} · peak ${meter}`,
+  ];
+  return {
+    ok: played,
+    message: `audio test · ${lines[0]!.replace(/\s+/, " ")} · ${lines[1]!.replace(/\s+/, " ")}`,
+    lines,
+  };
+}

package/src/audio/autotune-engine.ts

@@ -0,0 +1,101 @@
+/**
+ * The built-in pitch engine for autotune (0.7): the pitch lane's tracker
+ * (src/audio/dsp/pitch.ts) and PSOLA (src/audio/dsp/psola.ts) behind the
+ * `PitchEngine` seam of src/audio/autotune.ts. Curves are memoised per
+ * audio (`id ?? sha256`, else the buffer itself) and voice range; a file
+ * whose curve the analysis cache already holds is not tracked again. With
+ * `defer` (live play) a missing curve is tracked in the background and the
+ * buffer plays untuned until it is ready. Deterministic: the same audio
+ * always gives the same curve and the same tuned bytes.
+ */
+import { cachedPitchCurve } from "./analysis.ts";
+import {
+  PITCH_TRACKER_VERSION,
+  trackPitch,
+  trackPitchAsync,
+  type PitchCurve,
+} from "./dsp/pitch.ts";
+import { psola } from "./dsp/psola.ts";
+import type { PitchEngine, TunableBuffer } from "./autotune.ts";
+
+/** Curves kept in memory by key; older ones are tracked again on demand. */
+const CURVE_ENTRIES = 64;
+
+const curves = new Map<string, PitchCurve>();
+const anonymous = new WeakMap<Float32Array, Map<string, PitchCurve>>();
+const pending = new Set<string>();
+
+function keyOf(buffer: TunableBuffer): string | undefined {
+  return buffer.id ?? buffer.sha256;
+}
+
+function lookup(buffer: TunableBuffer, voice: string): PitchCurve | undefined {
+  const key = keyOf(buffer);
+  if (key === undefined) return anonymous.get(buffer.mono)?.get(voice);
+  const name = `${key}|${voice}`;
+  const hit = curves.get(name);
+  if (hit) {
+    curves.delete(name);
+    curves.set(name, hit);
+    return hit;
+  }
+  // The decoded file itself: the pitch lane's analysis cache may know it.
+  if (buffer.id === undefined && buffer.sha256 !== undefined) {
+    const cached = cachedPitchCurve(
+      buffer.sha256,
+      voice as Parameters<typeof cachedPitchCurve>[1],
+    );
+    if (cached) store(buffer, voice, cached);
+    return cached;
+  }
+  return undefined;
+}
+
+function store(buffer: TunableBuffer, voice: string, curve: PitchCurve): void {
+  const key = keyOf(buffer);
+  if (key === undefined) {
+    const byVoice = anonymous.get(buffer.mono) ?? new Map<string, PitchCurve>();
+    byVoice.set(voice, curve);
+    anonymous.set(buffer.mono, byVoice);
+    return;
+  }
+  const name = `${key}|${voice}`;
+  curves.delete(name);
+  curves.set(name, curve);
+  while (curves.size > CURVE_ENTRIES)
+    curves.delete(curves.keys().next().value!);
+}
+
+/** Drops the memoised curves (tests). */
+export function clearEngineCurves(): void {
+  curves.clear();
+  pending.clear();
+}
+
+/** The pitch lane's tracker and PSOLA as an autotune engine. */
+export const builtinPitchEngine: PitchEngine = Object.freeze({
+  version: `yin${PITCH_TRACKER_VERSION}-psola1`,
+  curve(buffer, voice, options) {
+    const hit = lookup(buffer, voice);
+    if (hit) return hit;
+    const x = Float64Array.from(buffer.mono);
+    if (!options?.defer) {
+      const curve = trackPitch(x, buffer.sampleRate, { voice });
+      store(buffer, voice, curve);
+      return curve;
+    }
+    const name = `${keyOf(buffer) ?? "anon"}|${voice}`;
+    if (!pending.has(name)) {
+      pending.add(name);
+      void trackPitchAsync(x, buffer.sampleRate, { voice }).then(
+        (curve) => {
+          pending.delete(name);
+          store(buffer, voice, curve);
+        },
+        () => pending.delete(name),
+      );
+    }
+    return undefined;
+  },
+  psola: (x, sampleRate, curve) => psola(x, sampleRate, curve),
+});