Spaces:

WolfDavid
/

japanese-learning-avatar

Running on Zero

WolfDavid commited on about 1 month ago

Commit

b4ca58d

1 Parent(s): 76d5860

feat(01-07): add tiered browser ASR and wire push-to-talk into the shared turn loop

- avatar/asr.js: transformers.js 4.2.0 from a pinned esm.sh URL, WebGPU when an adapter
really exists and WASM when it does not, announcing the active tier
- avatar/turn-loop.js: startListening/stopListening implemented once, imports mic.js and
asr.js itself so BOTH transports gained push-to-talk with zero changed lines
- avatar/facade.js: fan out events to turnLoop.observe so the loop learns speech-start
and speech-end without either transport knowing about the mic
- measured A/B over three models and three clips: default is whisper-base at q4
(135.8 MB, 779 ms WebGPU / 3636 ms WASM, CER 0.023), better-accuracy is
whisper-large-v3-turbo at q4f16 (537.4 MB, CER 0.000)
- two measured defects recorded in docs/ASR-TIERS.md: q8/int8/quantized cannot create a
session on the WASM backend at all, and a failed WebGPU init poisons the ONNX Runtime
backend registry so catch-and-retry is not a working fallback
- no remote ASR path exists; a seam guard fails the build if one appears

Files changed (8) hide show

avatar/asr-harness.html +327 -0
avatar/asr.js +244 -0
avatar/facade.js +11 -0
avatar/turn-loop.js +129 -4
docs/ASR-TIERS.md +200 -0
tests/fixtures/asr_ab_results.json +480 -0
tests/fixtures/make_asr_ab_results.py +313 -0
tests/test_transport_seam.py +76 -6

avatar/asr-harness.html ADDED Viewed

	@@ -0,0 +1,327 @@

+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>ASR harness - gate, tier and model A/B</title>
+    <style>
+      body {
+        font: 14px/1.5 system-ui, sans-serif;
+        margin: 0;
+        padding: 1rem 1.25rem;
+        background: #14161a;
+        color: #e6e8ec;
+      }
+      h1 {
+        font-size: 1rem;
+        letter-spacing: 0.04em;
+        text-transform: uppercase;
+        color: #8ba0b6;
+      }
+      #ptt-button {
+        font: inherit;
+        padding: 0.6rem 1.2rem;
+        border-radius: 999px;
+        border: 1px solid #3a4757;
+        background: #1e232b;
+        color: inherit;
+        cursor: pointer;
+      }
+      #ptt-button[data-listening='true'] {
+        background: #7a2230;
+        border-color: #b8404f;
+      }
+      pre {
+        background: #10131a;
+        border: 1px solid #262d38;
+        border-radius: 6px;
+        padding: 0.75rem;
+        white-space: pre-wrap;
+        word-break: break-word;
+      }
+      .tier {
+        color: #7fd1a2;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>ASR harness</h1>
+    <p>
+      No renderer, no host framework, no VRM. A fake stagePort is handed to the REAL
+      <code>createTurnLoop</code> and the REAL <code>installFacade</code>, so everything
+      exercised here is the same code both transports run.
+    </p>
+    <p>
+      <button id="ptt-button" type="button">hold to talk</button>
+      <span id="tier" class="tier">tier: (not loaded)</span>
+    </p>
+    <pre id="log">ready</pre>
+    <script type="module">
+      import { installFacade } from './facade.js';
+      import { createTurnLoop } from './turn-loop.js';
+      import { createAsr, MODELS, TIERS, hasWebGpu } from './asr.js';
+      import { GATE, REJECT, analyse, gate, isHallucination } from './mic.js';
+      const params = new URLSearchParams(location.search);
+      // ---------------------------------------------------------------- observability
+      window.__asrEvents = [];
+      window.__asrResults = null;
+      window.__pageErrors = [];
+      window.addEventListener('error', (e) => window.__pageErrors.push(String(e.message)));
+      window.addEventListener('unhandledrejection', (e) =>
+        window.__pageErrors.push(String(e.reason))
+      );
+      const logEl = document.getElementById('log');
+      const tierEl = document.getElementById('tier');
+      const button = document.getElementById('ptt-button');
+      function log(line) {
+        logEl.textContent = `${line}\n${logEl.textContent}`.split('\n').slice(0, 40).join('\n');
+      }
+      // ------------------------------------------------------------- the fake stage
+      // Six methods, no rendering. The stage core is proven separately by
+      // tests/e2e/test_stage_standalone.py; loading three.js and a 10 MiB VRM here would
+      // only make the ASR suite slower and its failures ambiguous.
+      const stageDebug = { ready: false, stage: 'fake', setListeningCalls: 0, setThinkingCalls: 0 };
+      const stagePort = {
+        async mount() {
+          stageDebug.ready = true;
+          return stageDebug;
+        },
+        async speak() {
+          return null;
+        },
+        async replayCached() {
+          throw new Error('nothing cached to re-play');
+        },
+        setThinking(value) {
+          stageDebug.setThinkingCalls += 1;
+          stageDebug.thinking = !!value;
+        },
+        setListening(value) {
+          stageDebug.setListeningCalls += 1;
+          stageDebug.listening = !!value;
+          button.dataset.listening = String(!!value);
+        },
+        async getDebug() {
+          return stageDebug;
+        },
+      };
+      // ----------------------------------------------------------------- the real loop
+      const asrOptions = {
+        model: params.get('model') || MODELS.default.model,
+        dtype: params.get('dtype') || MODELS.default.dtype,
+        device: params.get('device') || 'auto',
+      };
+      // ?processing=off drives the mic with echo cancellation, noise suppression and AGC
+      // all disabled. See the note on createMic: with Chrome's processing ON the cafe
+      // fixture is rejected by the RMS floor and the modulation condition never runs, so
+      // the suite exercises the gate in the configuration where it has no help.
+      const micOptions = { processing: params.get('processing') !== 'off' };
+      // The same deferred bus both transports use: createTurnLoop needs an emit before
+      // installFacade has built one, and events raised in between must not be dropped.
+      function deferredBus() {
+        let sink = null;
+        const queued = [];
+        const emit = (name, data) => {
+          if (sink) sink(name, data);
+          else queued.push([name, data]);
+        };
+        emit.connect = (real) => {
+          sink = real;
+          while (queued.length > 0) {
+            const [name, data] = queued.shift();
+            sink(name, data);
+          }
+        };
+        return emit;
+      }
+      const emit = deferredBus();
+      const turnLoop = createTurnLoop({ stagePort, emit, asrOptions, micOptions });
+      const installed = installFacade({ transport: 'harness', stagePort, turnLoop });
+      for (const name of ['ready', 'error', 'asr-tier', 'transcript', 'listening']) {
+        installed.avatar.on(name, (data) => {
+          window.__asrEvents.push({ event: name, data, at: performance.now() });
+          if (name === 'asr-tier') {
+            tierEl.textContent = `tier: ${data.tier} ${data.model} ${data.dtype} (${data.loadMs} ms)`;
+          }
+          log(`${name} ${JSON.stringify(data ?? null)}`);
+        });
+      }
+      emit.connect(installed.emit);
+      await installed.avatar.mount('');
+      // The control is plan 01-08's to own for real; this is the minimum needed to drive
+      // the same two facade methods a pointerdown/pointerup pair will drive there.
+      button.addEventListener('pointerdown', () => window.Avatar.startListening());
+      button.addEventListener('pointerup', () => window.Avatar.stopListening());
+      // ------------------------------------------------------------- test affordances
+      window.__events = (name) => window.__asrEvents.filter((e) => e.event === name);
+      window.__micDebug = () => ({ ...turnLoop.mic.__debug });
+      window.__asrDebug = () => ({ ...turnLoop.asr.__debug });
+      window.__gateConstants = () => ({ GATE, REJECT, TIERS, hasWebGpu: hasWebGpu() });
+      window.__gate = (samples, sampleRate) => gate(Float32Array.from(samples), sampleRate);
+      window.__analyse = (samples, sampleRate) => analyse(Float32Array.from(samples), sampleRate);
+      window.__isHallucination = (text, durationMs) => isHallucination(text, durationMs);
+      /** One full push-to-talk cycle, held for `holdMs`. Returns what the loop produced. */
+      window.__push = async (holdMs) => {
+        const started = await window.Avatar.startListening();
+        await new Promise((r) => setTimeout(r, holdMs));
+        const text = await window.Avatar.stopListening();
+        return { started, text, mic: { ...turnLoop.mic.__debug } };
+      };
+      // ------------------------------------------------------------------ the A/B rig
+      /** Decode a WAV URL to the mono 16 kHz Float32Array Whisper expects. */
+      async function loadClip(url) {
+        const bytes = await (await fetch(url)).arrayBuffer();
+        const Ctor = window.AudioContext || window.webkitAudioContext;
+        const ctx = new Ctor();
+        const decoded = await ctx.decodeAudioData(bytes.slice(0));
+        const frames = Math.round((decoded.duration * 16000));
+        const Offline = window.OfflineAudioContext || window.webkitOfflineAudioContext;
+        const offline = new Offline(1, frames, 16000);
+        const source = offline.createBufferSource();
+        source.buffer = decoded;
+        source.connect(offline.destination);
+        source.start(0);
+        const rendered = await offline.startRendering();
+        await ctx.close();
+        return {
+          samples: rendered.getChannelData(0).slice(),
+          durationSeconds: decoded.duration,
+          bytes: bytes.byteLength,
+        };
+      }
+      window.__loadClip = loadClip;
+      /** A bare ASR instance, so a driver can time a warm load on its own. */
+      window.__newAsr = (options) => createAsr({ ...options, emit: () => {} });
+      /** Measured gate statistics for a WAV URL, independent of any microphone. */
+      window.__measureClip = async (url) => {
+        const clip = await loadClip(url);
+        const verdict = gate(clip.samples, 16000);
+        return { url, ...verdict, sourceSeconds: clip.durationSeconds };
+      };
+      /**
+       * What the runtime actually stored, measured rather than looked up in a table.
+       * Cross-origin resource timing reports transferSize 0 without Timing-Allow-Origin,
+       * so the Cache API is the only honest source for "how many bytes is this model".
+       */
+      const MODEL_CACHE = 'transformers-cache';
+      window.__cacheBytes = async (modelId) => {
+        if (!('caches' in window)) return null;
+        const cache = await caches.open(MODEL_CACHE);
+        let total = 0;
+        let files = 0;
+        for (const request of await cache.keys()) {
+          if (modelId && !request.url.includes(modelId)) continue;
+          const response = await cache.match(request);
+          if (!response) continue;
+          total += (await response.blob()).size;
+          files += 1;
+        }
+        return { bytes: total, files };
+      };
+      /**
+       * The model A/B. candidates: [{model, dtype, device}], clips: [{url, reference}].
+       * Every number written to tests/fixtures/asr_ab_results.json comes from here.
+       *
+       * A COLD number comes from a fresh browser profile, never from deleting the
+       * cache: caches.delete() followed by caches.open() throws
+       * "Unexpected internal error" in Chromium 151 while the runtime still holds
+       * handles into the deleted cache.
+       */
+      window.__runAB = async (candidates, clips, options = {}) => {
+        const results = [];
+        const decoded = {};
+        for (const clip of clips) decoded[clip.url] = await loadClip(clip.url);
+        for (const candidate of candidates) {
+          const asr = createAsr({ ...candidate, emit: () => {} });
+          const record = {
+            model: candidate.model,
+            dtype: candidate.dtype,
+            requestedDevice: candidate.device || 'auto',
+            clips: [],
+          };
+          const loadStarted = performance.now();
+          try {
+            record.tier = await asr.init();
+          } catch (err) {
+            record.tier = null;
+            record.error = String(err?.message ?? err);
+            record.coldLoadMs = Math.round(performance.now() - loadStarted);
+            results.push(record);
+            log(`A/B FAILED ${candidate.model} ${candidate.dtype}: ${record.error}`);
+            continue;
+          }
+          record.coldLoadMs = asr.__debug.loadMs;
+          record.effectiveDtype = asr.__debug.dtype;
+          record.webgpuError = asr.__debug.webgpuError;
+          // Best-effort: CacheStorage.open() intermittently throws "Unexpected internal
+          // error" in Chromium 151 under a persistent context, and a size probe must
+          // never be able to discard a measurement run that already succeeded.
+          try {
+            record.cache = await window.__cacheBytes(candidate.model);
+          } catch (err) {
+            record.cache = { error: String(err?.message ?? err) };
+          }
+          // A second instantiation with the cache warm. The difference between the two
+          // is what a returning visitor actually experiences, and it is the number that
+          // decides whether a bigger default model is affordable.
+          if (options.warm) {
+            const warmStarted = performance.now();
+            const warmAsr = createAsr({ ...candidate, emit: () => {} });
+            try {
+              await warmAsr.init();
+              record.warmLoadMs = Math.round(performance.now() - warmStarted);
+            } catch (err) {
+              record.warmLoadError = String(err?.message ?? err);
+            }
+          }
+          for (const clip of clips) {
+            const c = decoded[clip.url];
+            const started = performance.now();
+            let transcript = null;
+            let error = null;
+            try {
+              transcript = (await asr.transcribe(c.samples, 16000)).text;
+            } catch (err) {
+              error = String(err?.message ?? err);
+            }
+            record.clips.push({
+              url: clip.url,
+              reference: clip.reference,
+              transcript,
+              error,
+              inferMs: Math.round(performance.now() - started),
+              clipSeconds: Number(c.durationSeconds.toFixed(3)),
+            });
+            log(`${candidate.model} ${clip.url.split('/').pop()} -> ${transcript}`);
+          }
+          results.push(record);
+        }
+        window.__asrResults = results;
+        return results;
+      };
+      window.__harnessReady = true;
+      log(`harness ready; navigator.gpu ${hasWebGpu() ? 'present' : 'absent'}`);
+    </script>
+  </body>
+</html>

avatar/asr.js ADDED Viewed

	@@ -0,0 +1,244 @@

+// avatar/asr.js
+//
+// BROWSER-SIDE JAPANESE ASR. WebGPU when the machine has it, WASM when it does not.
+//
+// Every tier here costs ZERO visitor GPU quota, which is the whole point: SC-4 asks
+// whether the turn loop still completes with the accelerated path disabled, and an ASR
+// that reached for hosted acceleration would make that answer a lie about listening
+// specifically. There is deliberately no remote transcription path in this file, and
+// tests/test_transport_seam.py::test_no_remote_asr_path_exists keeps it that way.
+//
+// Like mic.js this module runs in the PARENT document under both transports and is
+// imported by avatar/turn-loop.js, never by a transport file.
+//
+// Same esm.sh discipline as vrm-stage.js: one pinned URL, dynamically imported, no
+// import map. A pinned URL is the difference between a reproducible Space rebuild and
+// a model runtime that floats into a breaking release while nobody is watching.
+const TRANSFORMERS_URL = 'https://esm.sh/@huggingface/transformers@4.2.0';
+/** The two backends. Tier C - type instead of speak, VOIC-04 - is the universal floor
+ *  and lives outside this module by construction. */
+export const TIERS = {
+  WEBGPU: 'webgpu',
+  WASM: 'wasm',
+};
+/**
+ * The measured choice. See docs/ASR-TIERS.md for the A/B table these came from and for
+ * the caveat that the clips were synthesised, so the measured CER is a best case.
+ *
+ * THE DTYPE IS NOT NEGOTIABLE AND IS NOT q8. Measured on this stack, `q8`, `int8` and
+ * `quantized` all fail to create a session on the WASM backend at all:
+ *
+ *   Can't create a session. ERROR_CODE: 1, ERROR_MESSAGE: qdq_actions.cc:137
+ *   TransposeDQWeightsForMatMulNBits Missing required scale:
+ *   model.decoder.embed_tokens.weight_merged_0_scale
+ *
+ * for whisper-base, whisper-small and whisper-large-v3-turbo alike. They load fine on
+ * WebGPU, which is exactly how a q8 default would ship: green on the developer's machine
+ * and dead on every browser that lacks an adapter - the tier the fallback exists for.
+ * `q4` is the only quantisation measured working on BOTH tiers. 01-RESEARCH.md's
+ * "whisper-base with dtype:'q8'" recommendation predates this measurement.
+ */
+export const MODELS = {
+  default: { model: 'onnx-community/whisper-base', dtype: 'q4' },
+  accurate: { model: 'onnx-community/whisper-large-v3-turbo', dtype: 'q4f16' },
+};
+/** Frozen at the facade in plan 01-03; repeated here so the shape is visible at source. */
+export const TRANSCRIBE_OPTIONS = {
+  language: 'ja',
+  task: 'transcribe',
+  chunk_length_s: 30,
+  return_timestamps: false,
+};
+/** Whisper's feature extractor expects exactly this rate. */
+export const REQUIRED_SAMPLE_RATE = 16000;
+let modulePromise = null;
+/** One dynamic import for the whole page, however many pipelines get built on top. */
+function loadRuntime() {
+  if (!modulePromise) {
+    modulePromise = import(TRANSFORMERS_URL).then((mod) => {
+      // Without this the runtime probes a same-origin /models/ path first and the
+      // console fills with 404s that look like real failures.
+      if (mod.env) {
+        mod.env.allowLocalModels = false;
+        mod.env.allowRemoteModels = true;
+      }
+      return mod;
+    });
+  }
+  return modulePromise;
+}
+/** Does this browser expose the WebGPU API surface? Cheap, synchronous. NOT sufficient. */
+export function hasWebGpu() {
+  return typeof navigator !== 'undefined' && !!navigator.gpu;
+}
+/**
+ * Whether WebGPU can ACTUALLY be used, which is a different question from whether
+ * `navigator.gpu` exists.
+ *
+ * This probe is not defensive tidiness, it is load-bearing, and it is here because the
+ * obvious design does not work. Measured on this stack: when `navigator.gpu` is present
+ * but `requestAdapter()` resolves to null - the normal state of a headless browser, a
+ * machine whose GPU is blocklisted, or a browser started with GPU access denied - calling
+ * `pipeline(..., { device: 'webgpu' })` throws, AND POISONS THE ONNX RUNTIME BACKEND
+ * REGISTRY FOR THE WHOLE PAGE. A subsequent `pipeline(..., { device: 'wasm' })` for the
+ * same model then fails with the identical WebGPU error:
+ *
+ *   no available backend found. ERR: [webgpu] Error: Failed to get GPU adapter.
+ *
+ * So "feature-detect navigator.gpu, catch the failure, re-instantiate on WASM" - which is
+ * what 01-RESEARCH.md prescribes - produces an app that is broken for exactly the users
+ * the fallback exists to serve. Probing the adapter first means the doomed call is never
+ * made and the registry is never poisoned. The try/catch below stays as a second line of
+ * defence for failures a probe cannot predict, such as an out-of-memory adapter.
+ *
+ * @returns {Promise<{available: boolean, reason: string|null}>}
+ */
+export async function probeWebGpu() {
+  if (!hasWebGpu()) return { available: false, reason: 'navigator.gpu is not present' };
+  try {
+    const adapter = await navigator.gpu.requestAdapter();
+    if (!adapter) return { available: false, reason: 'requestAdapter() resolved to null' };
+    return { available: true, reason: null };
+  } catch (err) {
+    return { available: false, reason: String(err?.message ?? err) };
+  }
+}
+/**
+ * @param {object}   opts
+ * @param {Function} [opts.emit]    the facade event bus; 'asr-tier' is announced through it
+ * @param {string}   [opts.model]   defaults to the measured default model
+ * @param {string}   [opts.dtype]   dtype used on the WASM tier
+ * @param {string}   [opts.webgpuDtype] dtype used on the WebGPU tier
+ * @param {string}   [opts.device]  'auto' | 'webgpu' | 'wasm'; 'auto' feature-detects
+ */
+export function createAsr({
+  emit = () => {},
+  model = MODELS.default.model,
+  dtype = MODELS.default.dtype,
+  webgpuDtype = null,
+  device = 'auto',
+} = {}) {
+  const debug = {
+    tier: null,
+    model,
+    dtype: null,
+    loadMs: 0,
+    inferMs: 0,
+    transcribeCount: 0,
+    /** the API surface exists */
+    webgpuPresent: hasWebGpu(),
+    /** an adapter was actually obtained; null until init() has probed */
+    webgpuAvailable: null,
+    webgpuError: null,
+  };
+  let pipe = null;
+  let initPromise = null;
+  async function build(requestedTier) {
+    const { pipeline } = await loadRuntime();
+    if (requestedTier === TIERS.WEBGPU) {
+      const gpuDtype = webgpuDtype || dtype;
+      const built = await pipeline('automatic-speech-recognition', model, {
+        device: 'webgpu',
+        dtype: gpuDtype,
+      });
+      return { built, tier: TIERS.WEBGPU, dtype: gpuDtype };
+    }
+    // Ask for WASM by name rather than leaving `device` unset: the runtime's own
+    // auto-selection reaches for WebGPU whenever navigator.gpu exists, which is the
+    // same trap probeWebGpu() exists to avoid.
+    const built = await pipeline('automatic-speech-recognition', model, {
+      device: 'wasm',
+      dtype,
+    });
+    return { built, tier: TIERS.WASM, dtype };
+  }
+  /**
+   * Tier selection. WebGPU is opt-in and still labelled experimental upstream, so a
+   * failure to initialise it is an expected branch rather than an incident: catch it,
+   * record why, and re-instantiate on WASM. A learner must never see a broken app
+   * because their GPU adapter was busy.
+   */
+  async function init() {
+    if (initPromise) return initPromise;
+    initPromise = (async () => {
+      const started = performance.now();
+      let outcome = null;
+      // 'wasm' is the only value that skips the probe entirely; both 'auto' and an
+      // explicit 'webgpu' request are subject to it, because an explicit request that
+      // cannot be honoured must degrade rather than break the page.
+      if (device !== TIERS.WASM) {
+        const probe = await probeWebGpu();
+        debug.webgpuAvailable = probe.available;
+        if (!probe.available) debug.webgpuError = probe.reason;
+        if (probe.available) {
+          try {
+            outcome = await build(TIERS.WEBGPU);
+          } catch (err) {
+            debug.webgpuError = String(err?.message ?? err);
+            console.warn('WebGPU ASR init failed, falling back to WASM:', debug.webgpuError);
+            outcome = null;
+          }
+        }
+      } else {
+        debug.webgpuAvailable = false;
+      }
+      if (!outcome) outcome = await build(TIERS.WASM);
+      pipe = outcome.built;
+      debug.tier = outcome.tier;
+      debug.dtype = outcome.dtype;
+      debug.loadMs = Math.round(performance.now() - started);
+      emit('asr-tier', {
+        tier: debug.tier,
+        model: debug.model,
+        dtype: debug.dtype,
+        loadMs: debug.loadMs,
+      });
+      return debug.tier;
+    })();
+    return initPromise;
+  }
+  /**
+   * @param {Float32Array} samples mono
+   * @param {number} sampleRate must be 16000; mic.js already resamples
+   * @returns {Promise<{text:string, tier:string, model:string, inferMs:number}>}
+   */
+  async function transcribe(samples, sampleRate = REQUIRED_SAMPLE_RATE) {
+    if (sampleRate !== REQUIRED_SAMPLE_RATE) {
+      throw new Error(
+        `asr.transcribe expects ${REQUIRED_SAMPLE_RATE} Hz mono, got ${sampleRate} Hz`
+      );
+    }
+    await init();
+    const started = performance.now();
+    const out = await pipe(samples, { ...TRANSCRIBE_OPTIONS });
+    debug.inferMs = Math.round(performance.now() - started);
+    debug.transcribeCount += 1;
+    const text = String((Array.isArray(out) ? out[0]?.text : out?.text) ?? '').trim();
+    return { text, tier: debug.tier, model: debug.model, inferMs: debug.inferMs };
+  }
+  return {
+    __debug: debug,
+    init,
+    transcribe,
+    getTier: () => debug.tier,
+    getModel: () => debug.model,
+    isReady: () => pipe !== null,
+  };
+}

avatar/facade.js CHANGED Viewed

@@ -89,6 +89,17 @@ export function installFacade({ transport, stagePort, turnLoop, onEmit }) {
         }
       }
     }
     if (typeof onEmit === 'function') {
       try {
         onEmit(name, data);

         }
       }
     }
+    // The turn loop is the only transport-agnostic behaviour module, and it needs to
+    // know when speech starts and ends so the mic can refuse to open into the avatar's
+    // own voice. Handing it the event stream here keeps that knowledge out of both
+    // transports and out of window.Avatar.
+    if (typeof turnLoop.observe === 'function') {
+      try {
+        turnLoop.observe(name, data);
+      } catch (err) {
+        console.error('Avatar turn-loop observer failed', err);
+      }
+    }
     if (typeof onEmit === 'function') {
       try {
         onEmit(name, data);

avatar/turn-loop.js CHANGED Viewed

@@ -6,6 +6,17 @@
 // The renderer is reachable only through the six-method stagePort. The host bridge is
 // reachable only through getServer(), which is a GETTER rather than a value so this
 // module never holds a host object and can be constructed before the bridge exists.
 /**
  * A deferred method. Calling one now fails loudly and names the plan that fills it in,
@@ -23,22 +34,82 @@ function notWiredYet(name, plan) {
  * @param {object}   opts.stagePort   the renderer boundary
  * @param {Function} [opts.emit]      the facade's event bus
  * @param {Function} [opts.getServer] returns the host bridge, or null when there is none
  */
-export function createTurnLoop({ stagePort, emit = () => {}, getServer = () => null } = {}) {
   if (!stagePort) throw new Error('createTurnLoop: a stagePort is required');
   // The turn loop's own slice of __debug. The facade merges this object; it does not
-  // own it, and this module does not own the facade's.
   const state = {
     thinking: false,
     listening: false,
     lastTurnId: null,
     replayCount: 0,
   };
   return {
     state,
     getServer,
     setThinking(value) {
       const on = !!value;
@@ -69,8 +140,62 @@ export function createTurnLoop({ stagePort, emit = () => {}, getServer = () => n
       }
     },
-    startListening: notWiredYet('startListening', '01-07'),
-    stopListening: notWiredYet('stopListening', '01-07'),
     dispatchTurn: notWiredYet('dispatchTurn', '01-08'),
     requestSlower: notWiredYet('requestSlower', '01-08'),
   };

 // The renderer is reachable only through the six-method stagePort. The host bridge is
 // reachable only through getServer(), which is a GETTER rather than a value so this
 // module never holds a host object and can be constructed before the bridge exists.
+//
+// Push-to-talk landed in wave 4. Note that mic.js and asr.js are imported HERE and
+// constructed lazily by this module rather than being handed in by a transport: mic
+// capture and ASR run in the parent document under BOTH transports, and the iframe
+// transport has no AudioContext of its own to lend. Constructing them here means the
+// two transport files needed zero lines of change to gain push-to-talk, which is the
+// strongest possible form of the guarantee the seam exists to give. Both are still
+// injectable through the factory so a harness can substitute a different model.
+import { createAsr } from './asr.js';
+import { createMic, isHallucination, REJECT } from './mic.js';
 /**
  * A deferred method. Calling one now fails loudly and names the plan that fills it in,
  * @param {object}   opts.stagePort   the renderer boundary
  * @param {Function} [opts.emit]      the facade's event bus
  * @param {Function} [opts.getServer] returns the host bridge, or null when there is none
+ * @param {object}   [opts.mic]       overrides the mic built from avatar/mic.js
+ * @param {object}   [opts.asr]       overrides the ASR built from avatar/asr.js
+ * @param {object}   [opts.asrOptions] model/dtype/device overrides for the default ASR
+ * @param {object}   [opts.micOptions] capture overrides for the default mic
  */
+export function createTurnLoop({
+  stagePort,
+  emit = () => {},
+  getServer = () => null,
+  mic = null,
+  asr = null,
+  asrOptions = {},
+  micOptions = {},
+} = {}) {
   if (!stagePort) throw new Error('createTurnLoop: a stagePort is required');
   // The turn loop's own slice of __debug. The facade merges this object; it does not
+  // own it, and this module does not own the facade's. Every key is initialised here
+  // rather than on first use, because the parity suite compares __debug KEY SETS across
+  // transports and a lazily-added key would make that comparison time-dependent.
   const state = {
     thinking: false,
     listening: false,
     lastTurnId: null,
     replayCount: 0,
+    asrTier: null,
+    asrModel: null,
+    lastTranscript: null,
+    micRejectedCount: 0,
   };
+  let speaking = false;
+  function setListeningState(on) {
+    state.listening = on;
+    stagePort.setListening(on);
+  }
+  const micInstance =
+    mic ||
+    createMic({
+      emit,
+      onListening: setListeningState,
+      // Push-to-talk exists to make acoustic feedback impossible, so the mic refuses to
+      // open while the avatar is thinking or speaking. mic.js adds the 200 ms tail after
+      // speech-end on top of this.
+      isBusy: () => state.thinking || speaking,
+      ...micOptions,
+    });
+  const asrInstance = asr || createAsr({ emit, ...asrOptions });
+  /**
+   * The facade calls this for every event it fans out, under both transports - the
+   * iframe transport forwards the frame's events through the same bus. It is how this
+   * module learns that speech started or ended without holding a reference to the
+   * audio path, which belongs to the stage.
+   */
+  function observe(name, data) {
+    if (name === 'speech-start') {
+      speaking = true;
+    } else if (name === 'speech-end') {
+      speaking = false;
+      micInstance.noteSpeechEnd();
+    } else if (name === 'asr-tier' && data) {
+      state.asrTier = data.tier ?? null;
+      state.asrModel = data.model ?? null;
+    }
+  }
   return {
     state,
     getServer,
+    observe,
+    mic: micInstance,
+    asr: asrInstance,
     setThinking(value) {
       const on = !!value;
       }
     },
+    /**
+     * pointerdown on the push-to-talk control. Plan 01-08 wires the control itself;
+     * the behaviour is here so both transports get it from one implementation.
+     *
+     * @returns {Promise<boolean>} whether capture actually started
+     */
+    async startListening() {
+      const started = await micInstance.start();
+      if (!started) state.micRejectedCount = micInstance.__debug.rejectedCount;
+      return started;
+    },
+    /**
+     * pointerup. Gate -> ASR -> 'transcript'.
+     *
+     * A gated-out push emits NOTHING - not an empty transcript, which every downstream
+     * consumer would then have to special-case - and returns null.
+     *
+     * @returns {Promise<string|null>} the transcript, or null when nothing survived
+     */
+    async stopListening() {
+      const utterance = await micInstance.stop();
+      state.micRejectedCount = micInstance.__debug.rejectedCount;
+      if (!utterance.ok) return null;
+      let result;
+      try {
+        result = await asrInstance.transcribe(utterance.samples, utterance.sampleRate);
+      } catch (err) {
+        emit('error', { message: String(err?.message ?? err), where: 'stopListening' });
+        return null;
+      }
+      state.asrTier = asrInstance.getTier();
+      state.asrModel = asrInstance.getModel();
+      // Second line of defence: the audio passed the gate but Whisper still produced
+      // subtitle boilerplate. Only short pushes are eligible - see mic.js.
+      if (!result.text || isHallucination(result.text, utterance.durationMs)) {
+        micInstance.noteTranscriptRejected(
+          result.text ? REJECT.HALLUCINATION : REJECT.NO_AUDIO
+        );
+        state.micRejectedCount = micInstance.__debug.rejectedCount;
+        return null;
+      }
+      state.lastTranscript = result.text;
+      emit('transcript', {
+        text: result.text,
+        durationMs: Math.round(utterance.durationMs),
+        tier: result.tier,
+        gated: false,
+      });
+      return result.text;
+    },
     dispatchTurn: notWiredYet('dispatchTurn', '01-08'),
     requestSlower: notWiredYet('requestSlower', '01-08'),
   };

docs/ASR-TIERS.md ADDED Viewed

	@@ -0,0 +1,200 @@

+# ASR tiers and model choice (VOIC-02)
+Every number on this page was measured on this project's own audio, by
+`tests/fixtures/make_asr_ab_results.py` driving `avatar/asr-harness.html` in a real
+browser. The raw data is `tests/fixtures/asr_ab_results.json`. Nothing here is quoted
+from a model card.
+| | |
+|---|---|
+| Measured | 2026-08-27 |
+| Browser | Chromium 151.0.0.0 (Playwright), Windows NT 10.0 Win64 |
+| GPU adapter | `intel xe-lpg` (WebGPU available, **headed** Chromium only) |
+| Runtime | `https://esm.sh/@huggingface/transformers@4.2.0` |
+| Clips | `speech_ja.wav`, `speech_ja_long.wav`, `speech_ja_slow.wav` — VOICEVOX ずんだもん, plan 01-04 |
+---
+## Tier design
+| Tier | Path | GPU quota | Availability |
+|---|---|---|---|
+| **A** | `@huggingface/transformers` 4.2.0, `device: 'webgpu'` | **zero** | Chrome 113+ desktop, Chrome 121+ Android 12+, Safari macOS 26 / iOS 26, Firefox 141+ |
+| **B** | same library, `device: 'wasm'` | **zero** | everywhere WASM+SIMD works; several times slower |
+| **C** | type instead of speak (VOIC-04) | zero | universal — the true floor |
+| **D** | hosted whisper-large-v3-turbo on accelerated hardware | **burns visitor quota** | **NOT built, and must not be.** It would consume the exact resource SC-4 tests the loop's survival without |
+`tests/test_transport_seam.py::test_no_remote_asr_path_exists` fails the build if tier D
+ever appears in `avatar/`.
+---
+## Gate thresholds (measured against the committed fixtures)
+Read straight off the WAV files, independent of any microphone: 20 ms frames, `peak frame
+RMS / median frame RMS`. Reproduce with `window.__measureClip(url)` in the harness.
+| Fixture | duration | RMS | peak/median frame RMS | gate verdict | condition that fired |
+|---|---|---|---|---|---|
+| `silence_30s.wav` | 30.000 s | 0.00000 | ∞ (median is 0) | **REJECT** | `rms-floor` |
+| `cafe_noise_30s.wav` | 30.000 s | 0.05760 | **1.961** | **REJECT** | `envelope-modulation` |
+| `speech_ja.wav` | 1.056 s | 0.07153 | **10.711** | **ACCEPT** | — |
+| `speech_ja_long.wav` | 5.504 s | 0.05515 | 7.509 | **ACCEPT** | — |
+| `speech_ja_slow.wav` | 7.381 s | 0.04918 | 6.368 | **ACCEPT** | — |
+Thresholds: **300 ms** duration floor, **0.01** RMS floor, **2.5** modulation floor.
+The 2.5 figure is the whole reason the third condition exists. The café fixture is written
+at −24.8 dBFS — roughly **six times** the RMS floor — so an RMS-only gate passes it
+comfortably. It is rejected because steady broadband noise is not modulated: 1.961 against
+speech's 6.4–10.7. The threshold sits with ~28% headroom below the noise and a 2.5×
+margin below the least-modulated speech clip.
+### The same gate, measured through a real microphone
+Chromium fed the fixture as its capture device
+(`--use-file-for-fake-audio-capture`), which is the path a learner actually exercises.
+| Fixture | hold | browser audio processing | duration | RMS | modulation | verdict |
+|---|---|---|---|---|---|---|
+| `silence_30s.wav` | 3000 ms | on | 2731 ms | 0.00000 | ∞ | REJECT `rms-floor` |
+| `cafe_noise_30s.wav` | 3000 ms | on | 2731 ms | **0.00547** | 2.344 | REJECT `rms-floor` |
+| `speech_ja.wav` | 1100 ms | on | 768 ms | 0.15451 | 6.694 | ACCEPT |
+| `silence_30s.wav` | 3000 ms | **off** | 2731 ms | 0.00000 | ∞ | REJECT `rms-floor` |
+| `cafe_noise_30s.wav` | 3000 ms | **off** | 2304 ms | 0.04409 | **1.360** | REJECT `envelope-modulation` |
+| `speech_ja.wav` | 1400 ms | **off** | 1195 ms | 0.06717 | 15.012 | ACCEPT |
+| `speech_ja.wav` | 150 ms | **off** | 0 ms | — | — | REJECT `duration-floor` |
+**Chromium's WebRTC noise suppression is doing part of the gate's job for us** — it drops
+the café fixture from 0.0577 to 0.0055 RMS, below the floor, so the modulation condition
+is never consulted. That is a good outcome in production and a useless one in a test,
+because it would leave the third condition unexercised while the suite looked green.
+`tests/e2e/test_asr_standalone.py` therefore drives the harness with `?processing=off` and
+verifies the gate in its **pessimistic** configuration — the raw microphone every browser
+without WebRTC processing hands us anyway. Production keeps all three processing flags on.
+### The hallucination blocklist
+Applied to the transcript, not the audio, and only under **1.5 s**. Seven known Japanese
+subtitle-boilerplate strings, listed in `avatar/mic.js`.
+Deliberately **not** blocklisted: the bare polite form 「ありがとうございました」. It is an
+ordinary thing a learner says out loud, and swallowing a real utterance is a worse failure
+than echoing one hallucination.
+`tests/test_transport_seam.py::test_blocklist_does_not_swallow_ordinary_japanese` exists
+specifically so a later "helpful" edit cannot add it back.
+---
+## Model A/B
+CER is against the exact strings plan 01-04 handed to VOICEVOX, so the ground truth is
+known rather than transcribed. "CER no-punct" strips 、。 and spaces from both sides,
+because punctuation is a rendering choice rather than a mishearing. "infer" is the median
+of the three clips. "first load" is the `Content-Length` of the two ONNX files the runtime
+fetches.
+| Model | dtype | device asked | tier used | first load | cold load | warm load | infer (p50) | CER | CER no-punct |
+|---|---|---|---|---|---|---|---|---|---|
+| `whisper-base` | q4 | wasm | wasm | 135.8 MB | 4064 ms | 1617 ms | 3636 ms | 0.062 | **0.023** |
+| `whisper-base` | q4 | webgpu | webgpu | 135.8 MB | 4415 ms | 2152 ms | **779 ms** | 0.062 | **0.023** |
+| `whisper-small` | q4 | wasm | wasm | 285.5 MB | 7355 ms | 3908 ms | 15485 ms | 0.083 | 0.023 |
+| `whisper-small` | q4 | webgpu | webgpu | 285.5 MB | 12846 ms | 4480 ms | 1934 ms | 0.083 | 0.023 |
+| `whisper-large-v3-turbo` | q4f16 | webgpu | webgpu | 537.4 MB | 29413 ms | 4055 ms | 2858 ms | 0.063 | **0.000** |
+| `whisper-large-v3-turbo` | q4 | wasm | wasm | 723.9 MB | 20692 ms | 4113 ms | **68200 ms** | 0.063 | 0.000 |
+| `whisper-base` | **q8** | wasm | **SESSION FAILED** | 73.3 MB | 3471 ms | — | — | — | — |
+| `whisper-base` | q8 | webgpu | webgpu | 73.3 MB | 3474 ms | 2021 ms | 4679 ms | 0.021 | 0.000 |
+| `whisper-small` | **q8** | wasm | **SESSION FAILED** | 237.5 MB | 5867 ms | — | — | — | — |
+Transcripts, per clip, in `tests/fixtures/asr_ab_results.json`. The single error
+`whisper-base` makes on this material is writing 今日は**良い**天気 where VOICEVOX was given
+今日は**いい**天気 — the same word, the same reading, a different orthography. It is not a
+mishearing, which is why the punctuation-insensitive CER is 0.023 rather than 0.062.
+### The finding that changed the default: `q8` does not work on the WASM tier
+`01-RESEARCH.md` recommends `onnx-community/whisper-base` with `dtype: 'q8'`. Measured,
+that configuration **cannot create an inference session on the WASM backend at all**:
+```
+Can't create a session. ERROR_CODE: 1, ERROR_MESSAGE: qdq_actions.cc:137
+TransposeDQWeightsForMatMulNBits Missing required scale:
+model.decoder.embed_tokens.weight_merged_0_scale
+for node: model.decoder.embed_tokens.weight_transposed_DequantizeLinear
+```
+The same error appears for `whisper-base`, `whisper-small` and `whisper-large-v3-turbo`,
+and for the `int8` and `quantized` aliases. Every one of them loads fine on **WebGPU**,
+which is precisely how this would have shipped: green on a developer machine with a GPU,
+dead on every browser without one — the tier the fallback exists to serve. `q4` is the only
+quantisation measured working on **both** tiers, so `q4` is the default.
+### The other finding: the documented fallback does not fall back
+`01-RESEARCH.md` prescribes "feature-detect `navigator.gpu`, request `webgpu` when present,
+catch initialisation failure, re-instantiate on WASM." Measured, that does not work.
+When `navigator.gpu` exists but `requestAdapter()` resolves to `null` — a headless browser,
+a blocklisted GPU, a browser started without GPU access — calling
+`pipeline(..., { device: 'webgpu' })` throws **and poisons the ONNX Runtime Web backend
+registry for the rest of the page**. The subsequent `pipeline(..., { device: 'wasm' })` for
+the same model then fails with the identical WebGPU error:
+```
+no available backend found. ERR: [webgpu] Error: Failed to get GPU adapter.
+```
+So `avatar/asr.js` **probes for an actual adapter first** (`probeWebGpu()`) and only issues
+the WebGPU call when one exists. The doomed call is never made, so the registry is never
+poisoned. The `try`/`catch` remains as a second line of defence for failures a probe cannot
+predict, such as an out-of-memory adapter.
+`tests/test_transport_seam.py::test_asr_webgpu_fallback_is_real_not_aspirational` fails if
+`requestAdapter` ever disappears from `avatar/asr.js`.
+---
+## Default chosen
+**`onnx-community/whisper-base` at `q4`**, on WebGPU when an adapter is available and on
+WASM when it is not.
+- It is the **only** measured configuration that runs on **both** tiers. `q8` is smaller
+  (73.3 MB) and more accurate (CER 0.021), and it is disqualified outright because it
+  cannot create a session on WASM.
+- 135.8 MB first load, then ~1.6–2.2 s to warm from the browser cache.
+- 779 ms median inference on WebGPU, 3636 ms on WASM. Both leave room inside VOIC-05's
+  perceived-response budget; `whisper-small` at 15.5 s on WASM does not.
+- CER 0.023 ignoring punctuation, and its one error is an orthography choice for the same
+  word rather than a misheard one.
+**`whisper-small` is rejected** on the numbers: 2.1× the bytes of `whisper-base`, an
+*identical* punctuation-insensitive CER of 0.023, and 4.3× the WASM inference time. It is
+dominated on every axis that matters.
+**"Better accuracy" toggle: `onnx-community/whisper-large-v3-turbo` at `q4f16`, WebGPU
+only.** CER 0.000 on this material and 2858 ms median inference — but a 537.4 MB first
+load, and 68 s per clip if it ever ran on WASM, which is why it must never be offered
+without an adapter. Both entries live in `MODELS` in `avatar/asr.js`; plan 01-08 owns the
+control that switches between them.
+---
+## Honest caveats
+- These clips are **VOICEVOX-synthesised speech**: cleaner, more regular and better
+  articulated than a learner speaking into a laptop microphone in a room with a fan. Every
+  CER above is a **best case** and overstates real-world accuracy. Real-speech confirmation
+  is a manual verification in plan 01-10.
+- Phase 1's bar is "their transcript appears", not "the transcript is right". If the chosen
+  default turns out to be embarrassing on real speech, that is a Phase 2/3 input, not a
+  Phase 1 failure.
+- Three clips and two distinct sentences is a **small sample**. It is enough to rule
+  `whisper-small` out and to disqualify `q8`, and it is not enough to claim a CER figure
+  with confidence intervals.
+- Load and inference times are from one Windows laptop with an `intel xe-lpg` iGPU on one
+  network. A visitor on a phone will see different numbers, particularly on WASM.
+- WebGPU numbers required **headed** Chromium. Headless Chromium exposes `navigator.gpu`
+  and then returns a null adapter, so a headless re-run of the A/B records every candidate
+  as WASM. That is true, and useless as a comparison.
+- Tier D (hosted ASR on accelerated hardware) is deliberately not built: it would consume
+  visitor GPU quota and contradict SC-4.

tests/fixtures/asr_ab_results.json ADDED Viewed

	@@ -0,0 +1,480 @@

+{
+  "generated": "2026-08-27",
+  "harness": "avatar/asr-harness.html driven by Playwright Chromium",
+  "runtime": "https://esm.sh/@huggingface/transformers@4.2.0",
+  "headless": false,
+  "environment": {
+    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36",
+    "platform": "Win32",
+    "webgpuAvailable": true,
+    "adapter": "intel xe-lpg"
+  },
+  "referenceIsGroundTruth": "The reference strings are the exact inputs plan 01-04 handed to VOICEVOX, so CER is measured against known text, not against a human transcription.",
+  "caveat": "These clips are VOICEVOX-synthesised speech: cleaner and more regular than a learner speaking into a laptop microphone. Every CER here is a BEST CASE.",
+  "gate": [
+    {
+      "url": "http://127.0.0.1:8477/tests/fixtures/silence_30s.wav",
+      "ok": false,
+      "reason": "rms-floor",
+      "durationMs": 30000,
+      "rms": 0,
+      "modulation": Infinity,
+      "frameCount": 1500,
+      "sourceSeconds": 30,
+      "fixture": "silence_30s.wav"
+    },
+    {
+      "url": "http://127.0.0.1:8477/tests/fixtures/cafe_noise_30s.wav",
+      "ok": false,
+      "reason": "envelope-modulation",
+      "durationMs": 30000,
+      "rms": 0.05759779420430498,
+      "modulation": 1.9612655599696533,
+      "frameCount": 1500,
+      "sourceSeconds": 30,
+      "fixture": "cafe_noise_30s.wav"
+    },
+    {
+      "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+      "ok": true,
+      "reason": null,
+      "durationMs": 1056,
+      "rms": 0.07152851150220688,
+      "modulation": 10.710682777175906,
+      "frameCount": 52,
+      "sourceSeconds": 1.056,
+      "fixture": "speech_ja.wav"
+    },
+    {
+      "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+      "ok": true,
+      "reason": null,
+      "durationMs": 5504,
+      "rms": 0.05514636579038092,
+      "modulation": 7.5091750971935385,
+      "frameCount": 275,
+      "sourceSeconds": 5.504,
+      "fixture": "speech_ja_long.wav"
+    },
+    {
+      "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+      "ok": true,
+      "reason": null,
+      "durationMs": 7381.3125,
+      "rms": 0.049179610521588375,
+      "modulation": 6.3681243480621985,
+      "frameCount": 369,
+      "sourceSeconds": 7.381333333333333,
+      "fixture": "speech_ja_slow.wav"
+    }
+  ],
+  "clips": [
+    {
+      "wav": "speech_ja.wav",
+      "reference": "こんにちは"
+    },
+    {
+      "wav": "speech_ja_long.wav",
+      "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。"
+    },
+    {
+      "wav": "speech_ja_slow.wav",
+      "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。"
+    }
+  ],
+  "results": [
+    {
+      "model": "onnx-community/whisper-base",
+      "dtype": "q4",
+      "requestedDevice": "wasm",
+      "clips": [
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+          "reference": "こんにちは",
+          "transcript": "こんにちは",
+          "error": null,
+          "inferMs": 2510,
+          "clipSeconds": 1.056,
+          "cer": 0.0,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから、公園を散歩してから買い物に行きました。",
+          "error": null,
+          "inferMs": 3743,
+          "clipSeconds": 5.504,
+          "cer": 0.0625,
+          "cerNoPunctuation": 0.0345
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから 公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 3636,
+          "clipSeconds": 7.381,
+          "cer": 0.125,
+          "cerNoPunctuation": 0.0345
+        }
+      ],
+      "tier": "wasm",
+      "coldLoadMs": 4064,
+      "effectiveDtype": "q4",
+      "webgpuError": null,
+      "warmLoadMs": 1617,
+      "firstLoad": {
+        "files": {
+          "encoder_model_q4.onnx": 18772451,
+          "decoder_model_merged_q4.onnx": 123602419
+        },
+        "totalBytes": 142374870,
+        "totalMB": 135.8
+      },
+      "meanCerNoPunctuation": 0.023
+    },
+    {
+      "model": "onnx-community/whisper-base",
+      "dtype": "q4",
+      "requestedDevice": "webgpu",
+      "clips": [
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+          "reference": "こんにちは",
+          "transcript": "こんにちは",
+          "error": null,
+          "inferMs": 1182,
+          "clipSeconds": 1.056,
+          "cer": 0.0,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから、公園を散歩してから買い物に行きました。",
+          "error": null,
+          "inferMs": 779,
+          "clipSeconds": 5.504,
+          "cer": 0.0625,
+          "cerNoPunctuation": 0.0345
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから 公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 728,
+          "clipSeconds": 7.381,
+          "cer": 0.125,
+          "cerNoPunctuation": 0.0345
+        }
+      ],
+      "tier": "webgpu",
+      "coldLoadMs": 4415,
+      "effectiveDtype": "q4",
+      "webgpuError": null,
+      "warmLoadMs": 2152,
+      "firstLoad": {
+        "files": {
+          "encoder_model_q4.onnx": 18772451,
+          "decoder_model_merged_q4.onnx": 123602419
+        },
+        "totalBytes": 142374870,
+        "totalMB": 135.8
+      },
+      "meanCerNoPunctuation": 0.023
+    },
+    {
+      "model": "onnx-community/whisper-small",
+      "dtype": "q4",
+      "requestedDevice": "wasm",
+      "clips": [
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+          "reference": "こんにちは",
+          "transcript": "こんにちは",
+          "error": null,
+          "inferMs": 10241,
+          "clipSeconds": 1.056,
+          "cer": 0.0,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 15485,
+          "clipSeconds": 5.504,
+          "cer": 0.125,
+          "cerNoPunctuation": 0.0345
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 22609,
+          "clipSeconds": 7.381,
+          "cer": 0.125,
+          "cerNoPunctuation": 0.0345
+        }
+      ],
+      "tier": "wasm",
+      "coldLoadMs": 7355,
+      "effectiveDtype": "q4",
+      "webgpuError": null,
+      "warmLoadMs": 3908,
+      "firstLoad": {
+        "files": {
+          "encoder_model_q4.onnx": 66182104,
+          "decoder_model_merged_q4.onnx": 233149327
+        },
+        "totalBytes": 299331431,
+        "totalMB": 285.5
+      },
+      "meanCerNoPunctuation": 0.023
+    },
+    {
+      "model": "onnx-community/whisper-small",
+      "dtype": "q4",
+      "requestedDevice": "webgpu",
+      "clips": [
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+          "reference": "こんにちは",
+          "transcript": "こんにちは",
+          "error": null,
+          "inferMs": 2676,
+          "clipSeconds": 1.056,
+          "cer": 0.0,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 1568,
+          "clipSeconds": 5.504,
+          "cer": 0.125,
+          "cerNoPunctuation": 0.0345
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日は良い天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 1934,
+          "clipSeconds": 7.381,
+          "cer": 0.125,
+          "cerNoPunctuation": 0.0345
+        }
+      ],
+      "tier": "webgpu",
+      "coldLoadMs": 12846,
+      "effectiveDtype": "q4",
+      "webgpuError": null,
+      "warmLoadMs": 4480,
+      "firstLoad": {
+        "files": {
+          "encoder_model_q4.onnx": 66182104,
+          "decoder_model_merged_q4.onnx": 233149327
+        },
+        "totalBytes": 299331431,
+        "totalMB": 285.5
+      },
+      "meanCerNoPunctuation": 0.023
+    },
+    {
+      "model": "onnx-community/whisper-large-v3-turbo",
+      "dtype": "q4f16",
+      "requestedDevice": "webgpu",
+      "clips": [
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+          "reference": "こんにちは",
+          "transcript": "こんにちは",
+          "error": null,
+          "inferMs": 4199,
+          "clipSeconds": 1.056,
+          "cer": 0.0,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日はいい天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 2858,
+          "clipSeconds": 5.504,
+          "cer": 0.0938,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日はいい天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 2561,
+          "clipSeconds": 7.381,
+          "cer": 0.0938,
+          "cerNoPunctuation": 0.0
+        }
+      ],
+      "tier": "webgpu",
+      "coldLoadMs": 29413,
+      "effectiveDtype": "q4f16",
+      "webgpuError": null,
+      "warmLoadMs": 4055,
+      "firstLoad": {
+        "files": {
+          "encoder_model_q4f16.onnx": 369974078,
+          "decoder_model_merged_q4f16.onnx": 193505017
+        },
+        "totalBytes": 563479095,
+        "totalMB": 537.4
+      },
+      "meanCerNoPunctuation": 0.0
+    },
+    {
+      "model": "onnx-community/whisper-large-v3-turbo",
+      "dtype": "q4",
+      "requestedDevice": "wasm",
+      "clips": [
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+          "reference": "こんにちは",
+          "transcript": "こんにちは",
+          "error": null,
+          "inferMs": 68200,
+          "clipSeconds": 1.056,
+          "cer": 0.0,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日はいい天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 71643,
+          "clipSeconds": 5.504,
+          "cer": 0.0938,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日はいい天気ですから公園を散歩してから買い物に行きました",
+          "error": null,
+          "inferMs": 65004,
+          "clipSeconds": 7.381,
+          "cer": 0.0938,
+          "cerNoPunctuation": 0.0
+        }
+      ],
+      "tier": "wasm",
+      "coldLoadMs": 20692,
+      "effectiveDtype": "q4",
+      "webgpuError": null,
+      "warmLoadMs": 4113,
+      "firstLoad": {
+        "files": {
+          "encoder_model_q4.onnx": 424942775,
+          "decoder_model_merged_q4.onnx": 334147222
+        },
+        "totalBytes": 759089997,
+        "totalMB": 723.9
+      },
+      "meanCerNoPunctuation": 0.0
+    },
+    {
+      "model": "onnx-community/whisper-base",
+      "dtype": "q8",
+      "requestedDevice": "wasm",
+      "clips": [],
+      "tier": null,
+      "error": "Can't create a session. ERROR_CODE: 1, ERROR_MESSAGE: qdq_actions.cc:137 TransposeDQWeightsForMatMulNBits Missing required scale: model.decoder.embed_tokens.weight_merged_0_scale for node: model.decoder.embed_tokens.weight_transposed_DequantizeLinear",
+      "coldLoadMs": 3471,
+      "firstLoad": {
+        "files": {
+          "encoder_model_quantized.onnx": 23201314,
+          "decoder_model_merged_quantized.onnx": 53693315
+        },
+        "totalBytes": 76894629,
+        "totalMB": 73.3
+      },
+      "meanCerNoPunctuation": null
+    },
+    {
+      "model": "onnx-community/whisper-base",
+      "dtype": "q8",
+      "requestedDevice": "webgpu",
+      "clips": [
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja.wav",
+          "reference": "こんにちは",
+          "transcript": "こんにちは",
+          "error": null,
+          "inferMs": 2782,
+          "clipSeconds": 1.056,
+          "cer": 0.0,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_long.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日はいい天気ですから、公園を散歩してから買い物に行きました。",
+          "error": null,
+          "inferMs": 4817,
+          "clipSeconds": 5.504,
+          "cer": 0.0312,
+          "cerNoPunctuation": 0.0
+        },
+        {
+          "url": "http://127.0.0.1:8477/tests/fixtures/speech_ja_slow.wav",
+          "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+          "transcript": "今日はいい天気ですから、公園を散歩してから買い物に行きました。",
+          "error": null,
+          "inferMs": 4679,
+          "clipSeconds": 7.381,
+          "cer": 0.0312,
+          "cerNoPunctuation": 0.0
+        }
+      ],
+      "tier": "webgpu",
+      "coldLoadMs": 3474,
+      "effectiveDtype": "q8",
+      "webgpuError": null,
+      "warmLoadMs": 2021,
+      "firstLoad": {
+        "files": {
+          "encoder_model_quantized.onnx": 23201314,
+          "decoder_model_merged_quantized.onnx": 53693315
+        },
+        "totalBytes": 76894629,
+        "totalMB": 73.3
+      },
+      "meanCerNoPunctuation": 0.0
+    },
+    {
+      "model": "onnx-community/whisper-small",
+      "dtype": "q8",
+      "requestedDevice": "wasm",
+      "clips": [],
+      "tier": null,
+      "error": "Can't create a session. ERROR_CODE: 1, ERROR_MESSAGE: qdq_actions.cc:137 TransposeDQWeightsForMatMulNBits Missing required scale: model.decoder.embed_tokens.weight_merged_0_scale for node: model.decoder.embed_tokens.weight_transposed_DequantizeLinear",
+      "coldLoadMs": 5867,
+      "firstLoad": {
+        "files": {
+          "encoder_model_quantized.onnx": 92326160,
+          "decoder_model_merged_quantized.onnx": 156750845
+        },
+        "totalBytes": 249077005,
+        "totalMB": 237.5
+      },
+      "meanCerNoPunctuation": null
+    }
+  ]
+}

tests/fixtures/make_asr_ab_results.py ADDED Viewed

	@@ -0,0 +1,313 @@

+"""Produce tests/fixtures/asr_ab_results.json: the measured ASR model A/B.
+Run it, do not hand-edit its output::
+    uv run python tests/fixtures/make_asr_ab_results.py
+What it does, and why each part is measured rather than looked up:
+* Drives ``avatar/asr-harness.html`` over a loopback static server with real Playwright
+  Chromium, so every number comes from the same code path the Space will run.
+* Gives each candidate a **fresh browser profile** for its cold load, then reopens that
+  profile for the warm load. Deleting the runtime's CacheStorage instead would be
+  cheaper, but ``caches.delete()`` followed by ``caches.open()`` throws "Unexpected
+  internal error" in Chromium 151 while the runtime still holds handles into it.
+* Takes first-load size from the ``Content-Length`` of the exact ONNX files the runtime
+  fetches. Cross-origin resource timing reports ``transferSize: 0`` without
+  ``Timing-Allow-Origin``, so the browser cannot honestly report this to itself.
+* Includes the ``q8`` candidates **on purpose, expecting them to fail on WASM**. The
+  failure is the single most consequential finding of this exercise and it belongs in the
+  committed record, not in a commit message.
+WebGPU note: headless Chromium exposes ``navigator.gpu`` but returns a null adapter, so
+this script runs HEADED. A headless run will silently record every WebGPU candidate as
+having fallen back to WASM, which is true but useless as an A/B.
+"""
+from __future__ import annotations
+import argparse
+import datetime as dt
+import functools
+import http.server
+import json
+import shutil
+import socket
+import sys
+import tempfile
+import threading
+import time
+import urllib.request
+from pathlib import Path
+HERE = Path(__file__).resolve().parent
+REPO_ROOT = HERE.parent.parent
+OUT = HERE / "asr_ab_results.json"
+# The ground truth is exact because we generated the audio: plan 01-04 synthesised these
+# three clips from these three strings with VOICEVOX. No human transcribed anything.
+CLIPS = [
+    {"wav": "speech_ja.wav", "reference": "こんにちは"},
+    {
+        "wav": "speech_ja_long.wav",
+        "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+    },
+    {
+        "wav": "speech_ja_slow.wav",
+        "reference": "今日はいい天気ですから、公園を散歩してから、買い物に行きました。",
+    },
+]
+GATE_FIXTURES = ["silence_30s.wav", "cafe_noise_30s.wav", *[c["wav"] for c in CLIPS]]
+CANDIDATES = [
+    {"model": "onnx-community/whisper-base", "dtype": "q4", "device": "wasm"},
+    {"model": "onnx-community/whisper-base", "dtype": "q4", "device": "webgpu"},
+    {"model": "onnx-community/whisper-small", "dtype": "q4", "device": "wasm"},
+    {"model": "onnx-community/whisper-small", "dtype": "q4", "device": "webgpu"},
+    {"model": "onnx-community/whisper-large-v3-turbo", "dtype": "q4f16", "device": "webgpu"},
+    {"model": "onnx-community/whisper-large-v3-turbo", "dtype": "q4", "device": "wasm"},
+    # The q8 control group. 01-RESEARCH.md recommends exactly this configuration.
+    {"model": "onnx-community/whisper-base", "dtype": "q8", "device": "wasm"},
+    {"model": "onnx-community/whisper-base", "dtype": "q8", "device": "webgpu"},
+    {"model": "onnx-community/whisper-small", "dtype": "q8", "device": "wasm"},
+]
+SIZE_URL = "https://huggingface.co/{model}/resolve/main/onnx/{file}"
+# Punctuation is a rendering choice, not a transcription error, so CER is reported both
+# ways. A tutor cares about the second number.
+PUNCTUATION = "、。，．,.!?！？ 　\n\t"
+def levenshtein(a: str, b: str) -> int:
+    if a == b:
+        return 0
+    if not a:
+        return len(b)
+    if not b:
+        return len(a)
+    previous = list(range(len(b) + 1))
+    for i, ca in enumerate(a, start=1):
+        current = [i]
+        for j, cb in enumerate(b, start=1):
+            current.append(min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (ca != cb)))
+        previous = current
+    return previous[-1]
+def cer(hypothesis: str | None, reference: str) -> float | None:
+    if hypothesis is None:
+        return None
+    if not reference:
+        return None
+    return round(levenshtein(hypothesis, reference) / len(reference), 4)
+def strip_punctuation(text: str) -> str:
+    return "".join(c for c in text if c not in PUNCTUATION)
+def content_length(url: str) -> int | None:
+    request = urllib.request.Request(url, method="HEAD")  # noqa: S310
+    request.add_header("User-Agent", "japanese-learning-avatar/asr-ab")
+    try:
+        with urllib.request.urlopen(request, timeout=60) as response:  # noqa: S310
+            # LFS-backed files answer with x-linked-size; Content-Length is the pointer.
+            raw = response.headers.get("x-linked-size") or response.headers.get("Content-Length")
+            return int(raw) if raw else None
+    except OSError:
+        return None
+# transformers.js does not name the file after the dtype: `q8` resolves to the
+# `_quantized` suffix, not `_q8`. Getting this wrong silently reports "size unknown" for
+# exactly the candidate the whole q8 control group exists to size.
+DTYPE_SUFFIX = {
+    "fp32": "",
+    "fp16": "_fp16",
+    "q8": "_quantized",
+    "int8": "_int8",
+    "uint8": "_uint8",
+    "q4": "_q4",
+    "q4f16": "_q4f16",
+    "bnb4": "_bnb4",
+}
+def first_load_bytes(model: str, dtype: str) -> dict:
+    suffix = DTYPE_SUFFIX.get(dtype, f"_{dtype}")
+    files = [f"encoder_model{suffix}.onnx", f"decoder_model_merged{suffix}.onnx"]
+    sizes = {f: content_length(SIZE_URL.format(model=model, file=f)) for f in files}
+    known = [v for v in sizes.values() if isinstance(v, int)]
+    total = sum(known)
+    return {
+        "files": sizes,
+        "totalBytes": total if len(known) == len(files) else None,
+        "totalMB": round(total / 1024 / 1024, 1) if len(known) == len(files) else None,
+    }
+def start_server(port: int):
+    handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=str(REPO_ROOT))
+    try:
+        server = http.server.ThreadingHTTPServer(("127.0.0.1", port), handler)
+    except OSError:
+        with socket.socket() as probe:
+            probe.bind(("127.0.0.1", 0))
+            port = probe.getsockname()[1]
+        server = http.server.ThreadingHTTPServer(("127.0.0.1", port), handler)
+    server.daemon_threads = True
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server, f"http://127.0.0.1:{server.server_port}"
+WARM_LOAD = """
+async (candidate) => {
+  const started = performance.now();
+  const asr = window.__newAsr(candidate);
+  await asr.init();
+  return { warmLoadMs: Math.round(performance.now() - started), tier: asr.getTier() };
+}
+"""
+ENVIRONMENT = """
+async () => ({
+  userAgent: navigator.userAgent,
+  platform: navigator.platform,
+  webgpuAvailable: !!navigator.gpu,
+  adapter: await (async () => {
+    if (!navigator.gpu) return null;
+    const a = await navigator.gpu.requestAdapter();
+    if (!a) return 'adapter-null';
+    const i = a.info || {};
+    const parts = [i.vendor, i.architecture, i.device, i.description].filter(Boolean);
+    return parts.join(' ') || 'adapter-ok';
+  })(),
+})
+"""
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--port", type=int, default=8477)
+    parser.add_argument("--headless", action="store_true", help="records WASM-only numbers")
+    parser.add_argument("--out", type=Path, default=OUT)
+    args = parser.parse_args()
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        print("playwright is required: uv sync --extra dev && playwright install chromium")
+        return 2
+    server, base = start_server(args.port)
+    clips = [
+        {"url": f"{base}/tests/fixtures/{c['wav']}", "reference": c["reference"]} for c in CLIPS
+    ]
+    profiles = Path(tempfile.mkdtemp(prefix="jla-asr-ab-"))
+    environment: dict = {}
+    gate_rows: list[dict] = []
+    records: list[dict] = []
+    def open_page(pw, profile: Path):
+        context = pw.chromium.launch_persistent_context(
+            user_data_dir=str(profile),
+            headless=args.headless,
+            args=["--autoplay-policy=no-user-gesture-required"],
+        )
+        page = context.new_page()
+        page.set_default_timeout(0)
+        page.goto(f"{base}/avatar/asr-harness.html")
+        page.wait_for_function("() => window.__harnessReady === true", timeout=120_000)
+        return context, page
+    try:
+        with sync_playwright() as pw:
+            for index, candidate in enumerate(CANDIDATES):
+                profile = profiles / f"p{index}"
+                profile.mkdir(parents=True, exist_ok=True)
+                label = f"{candidate['model']} {candidate['dtype']} {candidate['device']}"
+                print(f"--- cold {label}", flush=True)
+                started = time.time()
+                context, page = open_page(pw, profile)
+                if not environment:
+                    environment = page.evaluate(ENVIRONMENT)
+                    print(f"    {environment}", flush=True)
+                    # The gate table: measured off the WAV files themselves, so it is
+                    # independent of any microphone, any fake device and any model.
+                    for wav in GATE_FIXTURES:
+                        gate_rows.append(
+                            page.evaluate(
+                                "(u) => window.__measureClip(u)",
+                                f"{base}/tests/fixtures/{wav}",
+                            )
+                            | {"fixture": wav}
+                        )
+                try:
+                    record = page.evaluate(
+                        "async ([c, clips]) => (await window.__runAB([c], clips))[0]",
+                        [candidate, clips],
+                    )
+                except Exception as err:  # noqa: BLE001 - a driver failure is data too
+                    record = {**candidate, "tier": None, "error": f"driver: {err}", "clips": []}
+                context.close()
+                record["requestedDevice"] = candidate["device"]
+                record.pop("cache", None)
+                print(f"    tier={record.get('tier')} {time.time() - started:.1f}s", flush=True)
+                if record.get("tier"):
+                    context, page = open_page(pw, profile)
+                    try:
+                        record["warmLoadMs"] = page.evaluate(WARM_LOAD, candidate)["warmLoadMs"]
+                    except Exception as err:  # noqa: BLE001
+                        record["warmLoadError"] = str(err)[:300]
+                    context.close()
+                    print(f"    warm={record.get('warmLoadMs')} ms", flush=True)
+                shutil.rmtree(profile, ignore_errors=True)
+                record["firstLoad"] = first_load_bytes(candidate["model"], candidate["dtype"])
+                for clip in record.get("clips", []):
+                    transcript = clip.get("transcript")
+                    reference = clip["reference"]
+                    clip["cer"] = cer(transcript, reference)
+                    clip["cerNoPunctuation"] = (
+                        cer(strip_punctuation(transcript), strip_punctuation(reference))
+                        if transcript is not None
+                        else None
+                    )
+                scored = [c["cerNoPunctuation"] for c in record.get("clips", [])]
+                scored = [v for v in scored if v is not None]
+                record["meanCerNoPunctuation"] = (
+                    round(sum(scored) / len(scored), 4) if scored else None
+                )
+                records.append(record)
+    finally:
+        server.shutdown()
+        server.server_close()
+        shutil.rmtree(profiles, ignore_errors=True)
+    payload = {
+        "generated": dt.date.today().isoformat(),
+        "harness": "avatar/asr-harness.html driven by Playwright Chromium",
+        "runtime": "https://esm.sh/@huggingface/transformers@4.2.0",
+        "headless": args.headless,
+        "environment": environment,
+        "referenceIsGroundTruth": (
+            "The reference strings are the exact inputs plan 01-04 handed to VOICEVOX, so "
+            "CER is measured against known text, not against a human transcription."
+        ),
+        "caveat": (
+            "These clips are VOICEVOX-synthesised speech: cleaner and more regular than a "
+            "learner speaking into a laptop microphone. Every CER here is a BEST CASE."
+        ),
+        "gate": gate_rows,
+        "clips": CLIPS,
+        "results": records,
+    }
+    args.out.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(f"wrote {args.out}", flush=True)
+    return 0
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_transport_seam.py CHANGED Viewed

@@ -22,8 +22,8 @@ AMPLITUDE_TOKENS = ["AnalyserNode", "getByteFrequencyData", "getFloatTimeDomainD
 TURN_SURFACE = ["startListening", "stopListening", "dispatchTurn", "requestSlower"]
 # Plan 01-07. Mic capture and ASR run in the PARENT document under both transports -
 # only rendering and audio playback live inside the iframe - so these modules must hang
-# off the shared turn loop, never off a transport. asr.js joins this list in task 2.
-AUDIO_IN = ["mic.js"]
 def src(name: str) -> str:
@@ -153,12 +153,15 @@ def test_audio_input_modules_are_gradio_free(name):
 @pytest.mark.parametrize("name", AUDIO_IN)
-def test_audio_input_modules_are_not_imported_by_a_transport(name):
-    """If a transport imported these directly, the other transport would silently lose
     push-to-talk - the exact failure mode the shared turn loop exists to prevent.
-    The positive half of this guard (turn-loop.js DOES import them) lands with the
-    wiring in task 2, as test_audio_input_modules_hang_off_the_turn_loop.
     """
     for transport in TRANSPORTS:
         assert name not in src(transport), (
             f"{transport} imports {name}; mic/ASR wiring belongs in avatar/turn-loop.js"
@@ -199,3 +202,70 @@ def test_gate_thresholds_match_the_measured_fixtures():
     assert "MIN_MODULATION: 2.5" in s
     assert "BLOCKLIST_MAX_MS: 1500" in s
     assert "REARM_TAIL_MS = 200" in s

 TURN_SURFACE = ["startListening", "stopListening", "dispatchTurn", "requestSlower"]
 # Plan 01-07. Mic capture and ASR run in the PARENT document under both transports -
 # only rendering and audio playback live inside the iframe - so these modules must hang
+# off the shared turn loop, never off a transport.
+AUDIO_IN = ["mic.js", "asr.js"]
 def src(name: str) -> str:
 @pytest.mark.parametrize("name", AUDIO_IN)
+def test_audio_input_modules_hang_off_the_turn_loop(name):
+    """Imported by turn-loop.js, by neither transport.
+    If a transport imported these directly, the other transport would silently lose
     push-to-talk - the exact failure mode the shared turn loop exists to prevent.
     """
+    assert f"./{name}" in src("turn-loop.js"), (
+        f"avatar/turn-loop.js must import {name} so BOTH transports get it at once"
+    )
     for transport in TRANSPORTS:
         assert name not in src(transport), (
             f"{transport} imports {name}; mic/ASR wiring belongs in avatar/turn-loop.js"
     assert "MIN_MODULATION: 2.5" in s
     assert "BLOCKLIST_MAX_MS: 1500" in s
     assert "REARM_TAIL_MS = 200" in s
+def test_no_remote_asr_path_exists():
+    """Tier D would burn the exact visitor GPU quota SC-4 tests the loop's survival
+    without, so no hosted transcription path may exist anywhere in avatar/."""
+    for name in ["asr.js", "mic.js", "turn-loop.js"]:
+        lowered = src(name).lower()
+        for tok in ["zerogpu", "spaces.gpu", "/api/asr", "@spaces"]:
+            assert tok not in lowered, (
+                f"{name} references {tok!r}; browser ASR must cost zero GPU quota"
+            )
+def test_asr_module_url_is_pinned():
+    s = src("asr.js")
+    assert s.count("https://esm.sh/@huggingface/transformers@4.2.0") == 1, (
+        "exactly one pinned runtime URL, same discipline as vrm-stage.js"
+    )
+    assert "importmap" not in s
+def test_asr_webgpu_fallback_is_real_not_aspirational():
+    """The fallback must probe for an ADAPTER, not merely for navigator.gpu.
+    Measured on this stack: when navigator.gpu exists but requestAdapter() resolves to
+    null, calling pipeline(..., {device:'webgpu'}) throws AND poisons the ONNX Runtime
+    backend registry for the whole page, so the subsequent WASM re-instantiation fails
+    with the same WebGPU error. Catch-and-retry alone is therefore not a working
+    fallback; the doomed call must never be made. Deleting this assertion re-introduces
+    a bug that only shows up on the machines the fallback exists for.
+    """
+    s = src("asr.js")
+    assert "navigator.gpu" in s
+    assert "webgpu" in s
+    assert "requestAdapter" in s, (
+        "avatar/asr.js checks navigator.gpu but never requests an adapter; that is the "
+        "exact naive check that ships a broken app to every machine without a GPU"
+    )
+    assert re.search(r"catch\s*\(", s), "no catch around the WebGPU init path"
+    assert s.count("language: 'ja'") == 1
+@pytest.mark.parametrize("key", ["asrTier", "asrModel", "lastTranscript", "micRejectedCount"])
+def test_push_to_talk_debug_keys_present(key):
+    assert key in src("turn-loop.js"), (
+        f"__debug.{key} is contributed by avatar/turn-loop.js, so both transports report it"
+    )
+@pytest.mark.parametrize("member", ["startListening", "stopListening"])
+def test_push_to_talk_is_implemented_not_deferred(member):
+    """The two methods this plan owns must no longer be notWiredYet stubs."""
+    s = src("turn-loop.js")
+    assert f"notWiredYet('{member}'" not in s, (
+        f"{member} is still a deferred stub in avatar/turn-loop.js"
+    )
+    assert f"async {member}(" in s, f"{member} must be implemented in avatar/turn-loop.js"
+@pytest.mark.parametrize("name", TRANSPORTS)
+def test_transports_gained_push_to_talk_without_gaining_code(name):
+    """The whole point of the seam: the iframe fallback got this feature for free."""
+    s = src(name)
+    for token in ["startListening", "stopListening", "mic.", "asr.", "createMic", "createAsr"]:
+        assert token not in s, (
+            f"{name} mentions {token!r}; push-to-talk must live only in avatar/turn-loop.js"
+        )