Deblur Pipeline

A sibling document to README.md. The main README covers this package's role as the host shim for distributed inference (knot headers, R2 ranges, LRU). This document covers a different surface that lives in the same package: the FORK / RACE / FOLD recovery engine for images, video, and audio.

Overview

You have a blurry photo, a noisy whisper, or a lossy video frame. You want the underlying signal back. Classical deconvolution (Wiener) gives you a closed-form answer in the frequency domain, but it depends on two parameters that nobody hands you up front: the blur width σ and the noise floor. Pick wrong and you either keep the blur or amplify ringing into a worse image than you started with.

This pipeline exposes a unified recovery API across all three modalities. Image deblur is mathematically the same operation as video frame restoration is the same shape as audio whisper recovery — they all reduce to a 1D or 2D inverse filter with edge-preserving cleanup. The shared vocabulary is sigma (deblur amount, auto-selected via the φ-attractor), noiseFloor (Wiener regularization, auto-estimable via Immerkær's median-of-Laplacians), method ('wiener' single-shot or 'rl' Richardson-Lucy iterative), and bilateral (edge- preserving post-pass to suppress Wiener ringing). Every parallel surface inside the engine is a fork/race/fold composition built on the same forkRaceFold primitive.

Quick start

Image (RGB JPEG/PNG/WebP, auto-detected):

import { deblurAnyImage, encodeRecoveredAsPNG } from '@a0n/distributed-inference-host/deblur';
import { writeFile } from 'node:fs/promises';

const result = await deblurAnyImage('photo.jpg', { sigma: 'auto', channelMode: 'luminance' });
await writeFile('photo-recovered.png', await encodeRecoveredAsPNG(result));
console.log(`σ=${result.selectedSigma.toFixed(3)}, noiseFloor=${result.noiseFloorUsed.toExponential(2)}`);

Video (ffmpeg-piped, frame-parallel):

import { deblurVideo } from '@a0n/distributed-inference-host/deblur';

await deblurVideo({
  input:  'clip.mp4',
  output: 'clip-recovered.mp4',
  workers: 4,
  options: { sigma: 'auto', channelMode: 'luminance' },
  onProgress: ({ current, fps }) => console.log(`frame ${current} @ ${fps.toFixed(1)} fps`),
});

Audio (mono Float32 PCM):

import { deblurAudio } from '@a0n/distributed-inference-host/deblur';

const result = await deblurAudio({
  audio: monoFloat32Pcm,
  sampleRate: 16000,
  mode: 'spectral-subtract',  // Boll 1979 noise reduction
  spectralSubtraction: { oversubtractionFactor: 2.0 },
});

Public API

The complete re-export list lives in src/deblur-public.ts. Anything not exported from there is considered internal.

The φ / √5 attractor

σ-selection uses the golden-ratio attractor. The selector evaluates a small grid of candidate σ values (φ-spaced, not linearly spaced — denser near the expected answer, sparser far away). For each candidate it measures the recovered high-band energy and folds the result through a Fibonacci sliding window. The principled pick is the candidate whose deficit ratio sits closest to φ; the Newton-step refinement that follows is √5-normalized because √5 is the closed-form constant in Binet's Fibonacci formula.

The same √5 shows up as the Hurwitz attractor inside gnosis-frf's Reynolds- adaptive spin window. The number-theoretic gap appears in both subsystems for the same reason — both are expressing convergence dynamics over a fork/race/ fold scheduler. The pipeline does not invent the number; it inherits it from the topology of how candidates compete and merge.

Performance

Conservative measurements on Apple Silicon, single-thread JS:

• 256×256 RGB single-shot Wiener: ~750 ms
• 512×512 RGB single-shot Wiener: ~1.5 s
• 64×64 σ-attractor sweep (7 candidates): ~30 ms
• Bilateral 256×256: ~1 s single-thread; ~250 ms with 4-tile FRF on multi-core
• Video 128×128 RGB inline: ~55 fps
• Video 256×256 RGB with 4 worker_threads: not yet measured (worker bundle in flight)

For production-grade 60 fps at 1080p, see docs/wasm-simd-fft-plan.md. The pure-JS FFT is the bottleneck; SIMD FFT moves the floor by 5-10× and lets the worker pool deliver 60 fps. Until that lands, treat the video numbers above as the ceiling for sub-frame work.

FRF philosophy

Every parallel surface in this pipeline is a fork/race/fold composition with the same primitive (forkRaceFold from src/frf.ts). The σ-attractor forks across candidates, races them on a φ-spaced grid, and folds via deficit- weighted merge. The bilateral filter forks across row tiles, races them in a worker pool, and folds by concatenation. The video pipeline forks frames across worker threads, races them through ffmpeg's input/output pipes, and folds back into the encoded stream in arrival order. See docs/FRF_PIPELINE.md for the full mapping with file/line citations.

Honest gaps

• Audio whisper recovery via the 2D image-deblur path (audio-deblur.ts mode: 'image-deblur') is structurally valid but mathematically incomplete. Use mode: 'spectral-subtract' for actual whisper amplification, or the new audio-pneuma-bridge.ts route via @a0n/bitwise/voice-flac once that ships.
• worker_threads in tests need a TS loader (vitest does not propagate one), so the test suite uses workers: 0 inline mode as a substitute. Production consumers running a built JS bundle get full parallelism — this is a test- rig limitation, not a runtime one.
• WASM SIMD FFT is planned, not implemented. See docs/wasm-simd-fft-plan.md. The current FFT is pure JS.

Pointers

• docs/FRF_PIPELINE.md — comprehensive FORK / RACE / FOLD subsystem map
• docs/wasm-simd-fft-plan.md — WASM SIMD acceleration roadmap
• src/attractor.ts — φ / √5 constants and the Fibonacci sliding window
• open-source/aether/src/glossolalia-moa.ts:160 — interfere(), the canonical token-decoder FRF that this pipeline mirrors
• open-source/gnosis/gnosis-frf/ — Rust rayon-replacement, same √5-Hurwitz attractor in its spin tuning