@framecast/rt 1.0.0

package/LICENSE

@@ -0,0 +1,18 @@
+@framecast/rt - the Framecast WebGPU inference runtime (rt.js, sr.js)
+
+Copyright (C) 2026 MONZik
+
+This library is free software: you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation, either version 3 of the License, or (at your
+option) any later version.
+
+This library is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+for more details: https://www.gnu.org/licenses/lgpl-3.0.html
+
+Note: this LGPL grant covers the runtime library as distributed in this
+package. The Framecast repository as a whole (extension, tools, training
+code) remains AGPL-3.0; the model weights are licensed separately (see
+WEIGHTS_LICENSE.md in the repository).

package/README.md

@@ -0,0 +1,78 @@
+# @framecast/rt
+
+Real-time neural frame interpolation on **raw WebGPU** - the runtime behind
+the [Framecast](https://github.com/MONZikWasTaken/Framecast) extension,
+packaged as a library. Hand-written WGSL compute kernels, no ML framework,
+~3 ms per generated frame at 720p on a mid-range GPU (RTX 4060 Ti).
+
+Requires a browser with WebGPU and `shader-f16` (Chrome 121+; Apple Silicon
+works).
+
+## Install
+
+```
+npm i @framecast/rt
+```
+
+Weights are **not** bundled - fetch them once from the Framecast release
+(2.9 MB) and cache as you like:
+
+```js
+const BASE = 'https://github.com/MONZikWasTaken/Framecast/releases/download/v1.0.0';
+const [bin, manifest] = await Promise.all([
+  fetch(`${BASE}/rt_v7s.bin`).then(r => r.arrayBuffer()),
+  fetch(`${BASE}/rt_v7s.json`).then(r => r.json()),
+]);
+```
+
+## Interpolate between two frames
+
+```js
+import { createRT } from '@framecast/rt';
+
+const adapter = await navigator.gpu.requestAdapter();
+const device = await adapter.requestDevice({
+  requiredFeatures: adapter.features.has('shader-f16') ? ['shader-f16'] : [],
+});
+
+// dimensions must be divisible by 16
+const rt = await createRT(device, {
+  w: 1280, h: 720,
+  weightsBin: bin, weightsManifest: manifest,
+  textureInput: true, textureOutput: true,
+});
+
+// frameA/frameB are GPUTextures (rgba8unorm, TEXTURE_BINDING);
+// out is rgba8unorm with STORAGE_BINDING
+rt.prepPair(frameA, frameB);   // t-free trunk, once per pair
+rt.runT(0.5, out);             // one mid; call again with any t in (0,1)
+```
+
+`prepPair` + `runT` is the real-time path: the trunk runs once per frame
+pair, each additional mid costs only the small t-conditioned head - that is
+what makes 4x-6x factors affordable.
+
+For one-off use (benchmarks, offline tools) there is also a buffer-mode API:
+`rt.run(rgbaA, rgbaB, t)` takes and returns `Uint8Array` RGBA pixels.
+
+## Squeeze the last 20%
+
+Kernel shapes are GPU-specific. Run the autotuner once per machine and pass
+the result in:
+
+```js
+import { createRT, tuneConvRB } from '@framecast/rt';
+
+const tune = await tuneConvRB(device, { ci: 192, co: 192, w16: 80, h16: 45 });
+localStorage.setItem('fcTune', JSON.stringify(tune));
+// ...next session:
+const rt = await createRT(device, { ...opts, convTune: JSON.parse(localStorage.getItem('fcTune')) });
+```
+
+## License
+
+**LGPL-3.0-or-later.** Embed it in anything, including commercial products;
+modifications to the library itself must be published. The model weights are
+licensed separately (non-commercial - see
+[WEIGHTS_LICENSE](https://github.com/MONZikWasTaken/Framecast/blob/main/WEIGHTS_LICENSE.md));
+for commercial weight licensing, get in touch.

package/index.d.ts

@@ -0,0 +1,57 @@
+/** Kernel autotune result for the register-blocked conv (per GPU + shape). */
+export interface ConvTune {
+  coc: number;
+  slab: number;
+  sg?: boolean;
+  ms?: number;
+}
+
+export interface CreateRTOptions {
+  /** Output width in pixels. Must be divisible by 16. */
+  w: number;
+  /** Output height in pixels. Must be divisible by 16. */
+  h: number;
+  /** Raw weights blob (the released .bin file). */
+  weightsBin: ArrayBuffer;
+  /** Weights manifest (the released .json file, parsed). */
+  weightsManifest: Record<string, { offset: number; shape: number[] }>;
+  /** Kernel tune from tuneConvRB; omit for safe defaults. */
+  convTune?: ConvTune | null;
+  /** Inputs are GPUTextures instead of RGBA8 CPU buffers. */
+  textureInput?: boolean;
+  /** Mids are written into GPUTextures instead of read back to CPU. */
+  textureOutput?: boolean;
+  /** Bake the static-region guard into the flow kernel. */
+  staticGuard?: boolean;
+}
+
+export interface RT {
+  /** Buffer mode only: interpolate one mid between two RGBA8 frames. */
+  run(rgbaA: Uint8Array, rgbaB: Uint8Array, t?: number): Promise<Uint8Array>;
+  /**
+   * Batched mids for every t. Buffer mode returns RGBA8 arrays; texture mode
+   * writes into outTexs and resolves null (nothing crosses the bus).
+   */
+  runMulti(
+    a: Uint8Array | GPUTexture,
+    b: Uint8Array | GPUTexture,
+    ts: number[],
+    outTexs?: GPUTexture[],
+  ): Promise<Uint8Array[] | null>;
+  /** Texture mode: run the t-free trunk once for a frame pair. */
+  prepPair(a: GPUTexture, b: GPUTexture): void;
+  /** Texture mode: one mid at timestep t into outTex (call prepPair first). */
+  runT(t: number, outTex: GPUTexture): void;
+  /** Per-pass GPU timings (requires timestamp-query). */
+  profile(rgbaA: Uint8Array, rgbaB: Uint8Array): Promise<string>;
+  readonly w: number;
+  readonly h: number;
+}
+
+export function createRT(device: GPUDevice, opts: CreateRTOptions): Promise<RT>;
+
+/** Bench conv kernel variants on the real shape; persist the result per GPU. */
+export function tuneConvRB(
+  device: GPUDevice,
+  shape: { ci: number; co: number; w16: number; h16: number },
+): Promise<ConvTune>;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@framecast/rt",
+  "version": "1.0.0",
+  "description": "Real-time neural frame interpolation on raw WebGPU: hand-written WGSL kernels, 2.9 MB model, ~3 ms per generated frame on a mid-range GPU. The runtime behind the Framecast extension.",
+  "type": "module",
+  "main": "./rt.js",
+  "exports": {
+    ".": "./rt.js",
+    "./sr": "./sr.js"
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "rt.js",
+    "sr.js",
+    "index.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "prepack": "node prepack.mjs"
+  },
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MONZikWasTaken/Framecast.git",
+    "directory": "packages/rt"
+  },
+  "homepage": "https://github.com/MONZikWasTaken/Framecast#readme",
+  "bugs": "https://github.com/MONZikWasTaken/Framecast/issues",
+  "keywords": [
+    "webgpu",
+    "wgsl",
+    "frame-interpolation",
+    "video",
+    "rife",
+    "machine-learning",
+    "real-time"
+  ],
+  "author": "MONZik",
+  "engines": {
+    "node": ">=18"
+  }
+}