animader-cli 0.0.0-stage → 0.1.1

package/lib/wav.mjs

@@ -0,0 +1,197 @@
+// The fixture's soundtrack helper: a deterministic, clearly labeled 16-bit
+// PCM WAV smoke tone. It is not party art or music, and it is never fetched
+// from the network. The RIFF header, an INFO/INAM label, and the sample
+// count are the contract the tests and the page can audit.
+//
+// Ownership: media bytes for the generated fixture. Writing the file and
+// hashing it are host adapter work.
+
+import { DemoError } from './errors.mjs';
+
+export const TONE_LABEL = 'Animader demo test tone (not music)';
+
+export const TONE = Object.freeze({
+  seconds: 8,
+  sampleRate: 48000,
+  channels: 2,
+  bitsPerSample: 16,
+  frequency: 440,
+  amplitude: 0.12,
+});
+
+const PCM = 1;
+const ENCODER = new TextEncoder();
+const DECODER = new TextDecoder();
+
+function toneError(message) {
+  return new DemoError('invalid_tone_duration', message, {
+    remedy: 'Use a positive finite duration the sample rate can represent exactly.',
+  });
+}
+
+function writeAscii(bytes, offset, text) {
+  for (let index = 0; index < text.length; index++) bytes[offset + index] = text.charCodeAt(index) & 0xff;
+}
+
+function writeChunkHeader(bytes, offset, id, size) {
+  writeAscii(bytes, offset, id);
+  new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).setUint32(offset + 4, size, true);
+}
+
+/**
+ * Create the labeled smoke tone as bytes. No file, network or browser is
+ * involved, so the same call is used by the prepare adapter and by tests.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.seconds]
+ * @param {number} [options.sampleRate]
+ * @param {number} [options.channels]
+ * @param {string} [options.label]
+ * @returns {Uint8Array}
+ */
+export function createTestTone(options = {}) {
+  const seconds = options.seconds ?? TONE.seconds;
+  const sampleRate = options.sampleRate ?? TONE.sampleRate;
+  const channels = options.channels ?? TONE.channels;
+  const label = options.label ?? TONE_LABEL;
+
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) {
+    throw toneError(`seconds must be a positive finite number; got ${String(seconds)}`);
+  }
+  if (!Number.isInteger(sampleRate) || sampleRate <= 0 || sampleRate > 384000) {
+    throw toneError(`sampleRate must be a positive integer; got ${String(sampleRate)}`);
+  }
+  if (!Number.isInteger(channels) || channels < 1 || channels > 2) {
+    throw toneError(`channels must be 1 or 2; got ${String(channels)}`);
+  }
+  const frames = Math.round(seconds * sampleRate);
+  if (frames < 2) throw toneError('the duration is too short to carry a frame');
+  if (Math.abs(frames / sampleRate - seconds) > 0.5 / sampleRate) {
+    throw toneError(`seconds ${seconds} cannot be represented exactly at ${sampleRate} Hz`);
+  }
+
+  const labelBytes = ENCODER.encode(`${String(label).replace(/\0/g, '')}\0`);
+  const labelPadded = labelBytes.length + (labelBytes.length % 2);
+  const listSize = 4 + 8 + labelPadded;
+  const dataBytes = frames * channels * 2;
+  const fileBytes = 12 + 8 + 16 + 8 + listSize + 8 + dataBytes;
+  const bytes = new Uint8Array(fileBytes);
+  const view = new DataView(bytes.buffer);
+
+  writeAscii(bytes, 0, 'RIFF');
+  view.setUint32(4, fileBytes - 8, true);
+  writeAscii(bytes, 8, 'WAVE');
+
+  let offset = 12;
+  writeChunkHeader(bytes, offset, 'fmt ', 16);
+  offset += 8;
+  view.setUint16(offset, PCM, true);
+  view.setUint16(offset + 2, channels, true);
+  view.setUint32(offset + 4, sampleRate, true);
+  view.setUint32(offset + 8, sampleRate * channels * 2, true);
+  view.setUint16(offset + 12, channels * 2, true);
+  view.setUint16(offset + 14, 16, true);
+  offset += 16;
+
+  writeChunkHeader(bytes, offset, 'LIST', listSize);
+  offset += 8;
+  writeAscii(bytes, offset, 'INFO');
+  offset += 4;
+  writeChunkHeader(bytes, offset, 'INAM', labelBytes.length);
+  offset += 8;
+  bytes.set(labelBytes, offset);
+  offset += labelPadded;
+
+  writeChunkHeader(bytes, offset, 'data', dataBytes);
+  offset += 8;
+  const dataOffset = offset;
+
+  const fade = Math.min(Math.round(sampleRate * 0.01), Math.floor(frames / 2));
+  for (let frame = 0; frame < frames; frame++) {
+    const envelope = Math.min(1, frame / fade, (frames - 1 - frame) / fade);
+    const sample = Math.round(Math.sin((2 * Math.PI * TONE.frequency * frame) / sampleRate) * TONE.amplitude * 32767 * envelope);
+    for (let channel = 0; channel < channels; channel++) {
+      view.setInt16(dataOffset + (frame * channels + channel) * 2, sample, true);
+    }
+  }
+
+  return bytes;
+}
+
+/**
+ * Read the RIFF metadata a fixture proof can audit without decoding audio.
+ *
+ * @param {Uint8Array|ArrayBuffer} input
+ * @returns {{format: string, audioFormat: number, channels: number, sampleRate: number,
+ *   byteRate: number, blockAlign: number, bitsPerSample: number, frames: number,
+ *   seconds: number, dataOffset: number, dataBytes: number, label: string|null}}
+ */
+export function readWavInfo(input) {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+  if (bytes.length < 44 || String.fromCharCode(...bytes.subarray(0, 4)) !== 'RIFF' || String.fromCharCode(...bytes.subarray(8, 12)) !== 'WAVE') {
+    throw new Error('not a RIFF/WAVE file');
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let audioFormat = null;
+  let channels = null;
+  let sampleRate = null;
+  let byteRate = null;
+  let blockAlign = null;
+  let bitsPerSample = null;
+  let dataOffset = null;
+  let dataBytes = null;
+  let label = null;
+
+  let offset = 12;
+  while (offset + 8 <= bytes.length) {
+    const id = String.fromCharCode(...bytes.subarray(offset, offset + 4));
+    const size = view.getUint32(offset + 4, true);
+    const body = offset + 8;
+    if (body + size > bytes.length) throw new Error(`WAV chunk ${id} overruns the file`);
+    if (id === 'fmt ') {
+      if (size < 16) throw new Error('WAV fmt chunk is short');
+      audioFormat = view.getUint16(body, true);
+      channels = view.getUint16(body + 2, true);
+      sampleRate = view.getUint32(body + 4, true);
+      byteRate = view.getUint32(body + 8, true);
+      blockAlign = view.getUint16(body + 12, true);
+      bitsPerSample = view.getUint16(body + 14, true);
+    } else if (id === 'data') {
+      dataOffset = body;
+      dataBytes = size;
+    } else if (id === 'LIST' && size >= 4 && String.fromCharCode(...bytes.subarray(body, body + 4)) === 'INFO') {
+      let at = body + 4;
+      const end = body + size;
+      while (at + 8 <= end) {
+        const subId = String.fromCharCode(...bytes.subarray(at, at + 4));
+        const subSize = view.getUint32(at + 4, true);
+        const subBody = at + 8;
+        if (subBody + subSize > end) break;
+        if (subId === 'INAM') {
+          label = DECODER.decode(bytes.subarray(subBody, subBody + subSize)).replace(/\0+$/, '');
+        }
+        at = subBody + subSize + (subSize % 2);
+      }
+    }
+    offset = body + size + (size % 2);
+  }
+
+  if (audioFormat === null || dataOffset === null || byteRate === null || blockAlign === null) {
+    throw new Error('WAV is missing its fmt or data chunk');
+  }
+  const frames = dataBytes / blockAlign;
+  return {
+    format: 'WAVE',
+    audioFormat,
+    channels,
+    sampleRate,
+    byteRate,
+    blockAlign,
+    bitsPerSample,
+    frames,
+    seconds: frames / sampleRate,
+    dataOffset,
+    dataBytes,
+    label,
+  };
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "animader-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The animader command line: project creation, dev server, build, standalone export and host/project doctor checks",
+  "type": "module",
+  "bin": {
+    "animader": "./bin/animader.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "CC0-1.0",
+  "dependencies": {
+    "animader": "0.1.1",
+    "esbuild": "0.24.2",
+    "@mr_hugo/pacer": "0.2.0",
+    "pngine": "4.1.0"
+  },
+  "optionalDependencies": {
+    "@mr_hugo/pacer-darwin-arm64": "0.2.0",
+    "@pngine/darwin-arm64": "4.1.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "lib",
+    "adapters",
+    "player",
+    "hello",
+    "starters",
+    "toolchain",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/router.mjs",
+    "./config": "./src/config.mjs",
+    "./new": "./src/commands/new.mjs",
+    "./dev": "./src/commands/dev.mjs",
+    "./build": "./src/commands/build.mjs",
+    "./export": "./src/commands/export.mjs",
+    "./doctor": "./src/commands/doctor.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node --test",
+    "release:accept": "node scripts/release-accept.mjs",
+    "release:accept:self-test": "node scripts/release-accept.mjs --self-test-missing-artifact"
+  }
+}