Migrating from v1

v2 is a ground-up rewrite: TensorFlow.js and every WebGL path are gone; the U-Net runs on a WebGPU runtime (by default WebNN fp16 or hand-written WGSL; ORT is opt-in), and all pre/post-processing is WGSL compute on one shared GPUDevice. It is a clean break — the API changed deliberately (see docs/archive/api-v2-spec.md for the rationale): v1 configured runs through instance flags set in the right order; v2 is stateless per call — the instance holds identity only (models, sessions, device), every run is fully described by its arguments.

// v1 — sync constructor, backend + context injection, ready-listener
const denoiser = new Denoiser('webgpu', canvasOrDevice);
denoiser.onBackendReady(() => { /* ... */ });

// v2 — async factory; share the device with your renderer
const denoiser = await Denoiser.create({ precision: 'fp16', quality: 'fast', device: renderer.backend.device });

You can no longer hand the denoiser a canvas; hand it a GPUDevice through the device option (with the default runtime), or share denoiser.device with your renderer. Only the opt-in ORT runtime keeps the old constraint: onnxruntime-web creates and owns its GPUDevice (#26107), so with ORT create the denoiser first.

// v1 — stateful: set modes/inputs, execute, receive via listener
denoiser.inputMode = 'imgData';
denoiser.outputMode = 'imgData';
denoiser.onExecute((result) => draw(result), 'imgData');
await denoiser.execute(colorImg, albedoImg, normalImg);

// v2 — one call, result returned
const img = await denoiser.denoise(colorImg, { albedo: albedoImg, normal: normalImg });
ctx.putImageData(img, 0, 0);

v2 throws typed errors instead of generic ones: DenoiserUnsupportedError (WebGPU/feature availability) and DenoiserInputError (mismatched sizes, missing aux, bad formats). Full signatures in the API reference.

v1 served .tza files from a /tzas directory or CDN, and v2's default runtime does too: default CDN (jsDelivr, models-v3), override with tzaUrl. Only the opt-in ORT runtime serves converted .onnx models (rt_ldr.onnx, rt_hdr_alb_nrm_small.fp16.onnx, …), with weightsUrl. Regenerate the ORT models from OIDN .tza weights any time with tools/onnx-convert (Python, no PyTorch).

During the 2.x alpha the default runtime changed from onnxruntime-web (ORT) to AutoRuntime, and ORT moved behind an explicit import. If you adopted an earlier 2.x build, update like this:

// before: ORT was the default, configured through Denoiser.create
const denoiser = await Denoiser.create({
  precision: 'fp16',
  weightsUrl: '/models',
  wasmPaths: '/ort/',
  splitAux: true,
});

// after, option 1 (recommended): the default AutoRuntime, OIDN .tza weights
const denoiser = await Denoiser.create({
  precision: 'fp16',
  tzaUrl: '/tzas',          // optional, defaults to the jsDelivr models-v3 CDN
  device,                   // optional: run on an existing GPUDevice
});

// after, option 2: keep ORT explicitly (npm i onnxruntime-web)
import { OrtRuntime } from 'denoiser/ort';
const denoiser = await Denoiser.create({
  runtime: new OrtRuntime({ weightsUrl: '/models', wasmPaths: '/ort/', splitAux: true }),
  precision: 'fp16',
});