Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

6.9 KB
Raw Blame
/**
 * Land a synthesized 16-bit WAV on disk as game/library-ready audio:
 * `<dir>/<basename>.ogg` (Vorbis via the system ffmpeg) or, when ffmpeg is
 * missing or the encode fails, `<dir>/<basename>.wav`. Shared by the offline
 * renderers of LLM-authored music (chiptune scores, drawn wave sketches) and
 * the Music Designer code engine's browser-recorded takes.
 */

import { randomUUID } from 'crypto';
import { rename } from 'fs/promises';
import { join } from 'path';
import { atomicWrite, unlinkGuarded } from './fileUtils.js';
import { findFfmpeg, runFfmpegProcess } from './ffmpeg.js';

/** Write `wav` (a WAV Buffer) into `dir`; resolves to the filename used. */
export async function writeWavAudioFile(wav, dir, basename) {
  const wavPath = join(dir, `${basename}.wav`);
  const oggPath = join(dir, `${basename}.ogg`);
  await atomicWrite(wavPath, wav); // ensureDir + temp-rename
  const bin = await findFfmpeg();
  if (!bin) {
    // WAV fallback: drop any stale <basename>.ogg from an earlier
    // ffmpeg-equipped write, or a consumer still referencing it would play the
    // old audio while the source says otherwise.
    await unlinkGuarded(oggPath).catch(() => {});
    return `${basename}.wav`;
  }
  // Encode to a sibling temp file and rename over the destination: ffmpeg
  // truncates and writes THROUGH a leaf symlink at `oggPath`, a rename replaces
  // the link itself (#10894).
  const stagedOgg = `${oggPath}.${randomUUID()}.tmp`;
  const result = await runFfmpegProcess({ bin, args: ['-y', '-i', wavPath, '-c:a', 'libvorbis', '-q:a', '5', '-f', 'ogg', stagedOgg] });
  const landed = result.ok && await rename(stagedOgg, oggPath).then(() => true, (err) => {
    console.error(`❌ OGG rename failed (keeping WAV): ${err.message}`);
    return false;
  });
  if (!landed) {
    if (!result.ok) console.error(`❌ OGG encode failed (keeping WAV): ${result.reason}`);
    await unlinkGuarded(stagedOgg).catch(() => {}); // partial encode output
    await unlinkGuarded(oggPath).catch(() => {}); // stale output from an earlier write
    return `${basename}.wav`;
  }
  await unlinkGuarded(wavPath).catch(() => {});
  return `${basename}.ogg`;
}

/**
 * Locate a RIFF/WAVE buffer's `fmt ` and `data` chunks. Scans the whole
 * sub-chunk list (the two are not guaranteed to be adjacent or first) and
 * clamps `data` to the bytes actually present — a truncated stream can carry a
 * larger declared size than the buffer holds. Null for anything not RIFF/WAVE.
 */
function findWavChunks(buffer) {
  if (!Buffer.isBuffer(buffer) || buffer.length < 12) return null;
  if (buffer.toString('ascii', 0, 4) !== 'RIFF' || buffer.toString('ascii', 8, 12) !== 'WAVE') return null;
  let fmt = null;
  let data = null;
  let offset = 12;
  while (offset + 8 <= buffer.length) {
    const id = buffer.toString('ascii', offset, offset + 4);
    const size = buffer.readUInt32LE(offset + 4);
    const body = offset + 8;
    if (id === 'fmt ' && body + 16 <= buffer.length) fmt = { offset: body, size };
    else if (id === 'data') data = { offset: body, size: Math.min(size, buffer.length - body) };
    // Chunks are word-aligned: an odd size carries a trailing pad byte.
    offset = body + size + (size % 2);
  }
  return { fmt, data };
}

/**
 * Compute the playback duration (ms) of a PCM WAV buffer by reading its
 * canonical RIFF header — `data` chunk size ÷ `fmt ` byte rate. Used by the
 * narration timeline (karaoke-style highlight sync) where the client needs a
 * per-segment duration without decoding the audio itself, and to validate an
 * uploaded code-engine take (a non-WAV body measures 0).
 *
 * Pure + defensive: returns 0 for anything that isn't a parseable WAV so a
 * malformed buffer degrades to "unknown length" instead of throwing into the
 * synth path.
 */
export function wavDurationMs(buffer) {
  const chunks = findWavChunks(buffer);
  if (!chunks?.fmt || !chunks.data) return 0;
  const byteRate = buffer.readUInt32LE(chunks.fmt.offset + 8);
  if (!byteRate || !chunks.data.size) return 0;
  return Math.round((chunks.data.size / byteRate) * 1000);
}

const WAVE_FORMAT_PCM = 1;
const WAVE_FORMAT_IEEE_FLOAT = 3;
const WAVE_FORMAT_EXTENSIBLE = 0xfffe;

/** Sample decoder for one (format, bit depth) pair, normalized to [-1, 1]; null when unsupported. */
function sampleReader(format, bits) {
  if (format === WAVE_FORMAT_PCM && bits === 16) return (buf, at) => buf.readInt16LE(at) / 32768;
  if (format === WAVE_FORMAT_PCM && bits === 24) return (buf, at) => buf.readIntLE(at, 3) / 8388608;
  if (format === WAVE_FORMAT_PCM && bits === 32) return (buf, at) => buf.readInt32LE(at) / 2147483648;
  if (format === WAVE_FORMAT_IEEE_FLOAT && bits === 32) return (buf, at) => buf.readFloatLE(at);
  if (format === WAVE_FORMAT_IEEE_FLOAT && bits === 64) return (buf, at) => buf.readDoubleLE(at);
  return null;
}

/**
 * Decode a rendered WAV and measure what is actually in it, so a native
 * renderer's output is judged by its samples rather than by the score it was
 * asked to play: `{ channels, sampleRate, bitsPerSample, float, frames,
 * durationMs, peak, rms, nonFinite }`. `peak`/`rms` are over every finite
 * sample, normalized to full scale; `nonFinite` counts NaN/Infinity samples (a
 * float render can carry them). Accepts PCM 16/24/32-bit and IEEE float 32/64,
 * including WAVE_FORMAT_EXTENSIBLE. Null for anything else — never throws.
 */
export function measureWavAudio(buffer) {
  const chunks = findWavChunks(buffer);
  if (!chunks?.fmt || !chunks.data) return null;
  const { offset } = chunks.fmt;
  let format = buffer.readUInt16LE(offset);
  const channels = buffer.readUInt16LE(offset + 2);
  const sampleRate = buffer.readUInt32LE(offset + 4);
  const blockAlign = buffer.readUInt16LE(offset + 12);
  const bitsPerSample = buffer.readUInt16LE(offset + 14);
  // EXTENSIBLE carries the real format as the first two bytes of its subformat GUID.
  if (format === WAVE_FORMAT_EXTENSIBLE && chunks.fmt.size >= 40 && offset + 26 <= buffer.length) {
    format = buffer.readUInt16LE(offset + 24);
  }
  const read = sampleReader(format, bitsPerSample);
  const bytesPerSample = bitsPerSample / 8;
  if (!read || !channels || !sampleRate || blockAlign !== channels * bytesPerSample) return null;
  const frames = Math.floor(chunks.data.size / blockAlign);
  let peak = 0;
  let sumSquares = 0;
  let finite = 0;
  let nonFinite = 0;
  const end = chunks.data.offset + frames * blockAlign;
  for (let at = chunks.data.offset; at < end; at += bytesPerSample) {
    const sample = read(buffer, at);
    if (!Number.isFinite(sample)) { nonFinite += 1; continue; }
    const magnitude = Math.abs(sample);
    if (magnitude > peak) peak = magnitude;
    sumSquares += sample * sample;
    finite += 1;
  }
  return {
    channels,
    sampleRate,
    bitsPerSample,
    float: format === WAVE_FORMAT_IEEE_FLOAT,
    frames,
    durationMs: Math.round((frames / sampleRate) * 1000),
    peak,
    rms: finite ? Math.sqrt(sumSquares / finite) : 0,
    nonFinite,
  };
}