Choosing a runtime

Denoiser splits the work in two. The engine owns everything that doesn't depend on how the network is executed: tiling and overlap blending, the sRGB / OIDN PU transfer and autoexposure, aux-input encoding, resolve and texture IO. A NetworkRuntime only runs the U-Net, taking an NCHW buffer and producing an NCHW buffer on the shared GPUDevice. The same OIDN weights run on every runtime; only the executor changes, so you pick one by passing it to Denoiser.create({ runtime }). When you pass none, Denoiser uses AutoRuntime.

The auto, kernels, WGSL and WebNN runtimes read the upstream OIDN .tza weights (fetched from jsDelivr, models-v3, by default, or from { tzaUrl }). ORT reads the converted .onnx files. See Models & weights.

Mean over models, 1080p, denoiseTextures to a texture, warm median, Apple M5 Pro with an idle GPU, headless Chrome 154. Multiples are against native OIDN on Metal. Source: docs/status/eval-2026-10-08-quiet.md.

Quality is measured against native OIDN on the CPU (the reference implementation, same weights), as PSNR and maximum 8-bit difference:

One case, eiffel/rt_ldr_calb_cnrm, is 5 LSB from native on every runtime identically (70.1 dB). That is a shared pre/post difference, not a runtime problem, and it is still open.

All runtimes plug into the same Denoiser. Import the runtime from its subpath entry and pass it as runtime. The facade, the options and the output are unchanged.

npm install onnxruntime-web   # optional peer dependency of denoiser

import { Denoiser } from 'denoiser';
import { OrtRuntime } from 'denoiser/ort';

const denoiser = await Denoiser.create({
  runtime: new OrtRuntime({ weightsUrl: '/models' }), // { weightsUrl?, wasmPaths?, graphCapture?, splitAux? }
  precision: 'fp16',
});

The root denoiser entry never loads onnxruntime-web. The ORT options (weightsUrl, wasmPaths, graphCapture, splitAux) are OrtRuntime options, not Denoiser.create options. ORT creates its own GPUDevice and cannot adopt one you pass, so with three.js create the denoiser first (see three.js render targets).

import { Denoiser } from 'denoiser';
import { WgslRuntime } from 'denoiser/wgsl';

const denoiser = await Denoiser.create({
  runtime: new WgslRuntime(), // or { tzaUrl: '/tzas' } to self-host the weights
  precision: 'fp16',          // 'fp32' | 'fp16'
});

No runtime dependencies. fp32 uses the portable vec4 conv kernel. On devices with Chrome's chromium-experimental-subgroup-matrix feature (today only behind --enable-unsafe-webgpu) fp32 uses an 8x8 subgroup-matrix kernel that is faster (the 39.5 / 76.3 / 186 ms row above); everyone else gets the portable kernel. For fp16 the portable kernel with f16 sums is used because it is faster than the matrix path (forcing the matrix path at fp16 was about 20% slower on base).

import { Denoiser } from 'denoiser';
import { WebnnRuntime } from 'denoiser/webnn';

if (!WebnnRuntime.isAvailable()) {
  // navigator.ml / MLGraphBuilder missing: fall back to WgslRuntime
}

const denoiser = await Denoiser.create({
  runtime: new WebnnRuntime({ deviceType: 'gpu' }), // 'gpu' (default) | 'npu' | 'cpu'
  precision: 'fp16',
});

Launch Chrome with:

--enable-features=WebMachineLearningNeuralNetwork
# and, to reach the Apple Neural Engine with deviceType: 'npu':
--enable-features=WebMachineLearningNeuralNetwork,WebNNCoreMLExplicitGPUOrNPU

Caveats worth knowing before you ship anything on it:

import { Denoiser } from 'denoiser';
import { KernelsRuntime } from 'denoiser/kernels';

const denoiser = await Denoiser.create({
  runtime: new KernelsRuntime(), // weights from jsDelivr, or { tzaUrl: '/tzas' }
});

@huggingface/kernels is an optional peer dependency. Install it to use this entry. Today (0.0.1-preview.3) it always creates its own GPUDevice, so the runtime hands it yours through a navigator.gpu.requestAdapter shim (shareDeviceWithKernels). That is needed for zero-copy IO and is not meant for production use. Never call kernels' disposeSharedKernelRuntime() while it runs on a shared device, because it destroys that device. kernels keeps one page-global runtime, so all KernelsRuntimes on a page share one device (the first one's). The first load costs about 0.8-1.8 s per model (kernel fetch and compile).

import { Denoiser } from 'denoiser';

// the default: same as `runtime: new AutoRuntime({ tzaUrl, device })`
const denoiser = await Denoiser.create({
  precision: 'fp16',
  tzaUrl: '/tzas', // optional: self-host the .tza weights
  device,          // optional: run on an existing GPUDevice, e.g. a three.js renderer's
});

// explicit, with the WebNN control:
import { AutoRuntime } from 'denoiser/auto'; // also exported from 'denoiser'
const same = await Denoiser.create({
  runtime: new AutoRuntime({ webnn: 'gpu' }), // { tzaUrl?, device?, webnn?: 'gpu' | 'npu' | false }
  precision: 'fp16',
});

Per model it chooses WebNN (fp16, base/large models, when navigator.ml can create a context) or the hand-written WGSL runtime (everything else, including all fp32). Both run on one GPUDevice — pass a three.js renderer's device as device to share it — so denoiser.device stays the same when the model changes. runtime.lastChoice reports what served the last load. Set webnn: false when first-call latency matters more than steady-state speed: WebNN compiles per image size (0.4–2.7 s each on a cold CoreML cache).

ORT creates the GPUDevice it runs on and ignores one you inject. The other runtimes (including the default AutoRuntime) create a device with the adapter's maximum limits and features, or adopt the device you pass, either as the Denoiser.create({ device }) option or in the runtime's own options. Either way, build your own pipelines on denoiser.device, as described in The GPUDevice and Custom engines & raw WebGPU.

These live demos have a runtime picker (it reloads the page with ?runtime=; auto, wgsl, webnn, ort and kernels are accepted). WebNN is greyed out unless the browser exposes it (Chrome flag WebMachineLearningNeuralNetwork).

The harness is tools/eval (native OIDN, the reference) plus examples/eval (the web runtimes). It runs 25 scene/model cases, with every input rounded to fp16 so each setup sees the same data. See tools/eval/README.md. The full tables, including cold-start times, are in docs/status/eval-2026-10-08-quiet.md and docs/status/eval-2026-10-07.md in the repository.