@openipc-rs/web 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openipc-rs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @openipc-rs/web
+
+WebAssembly and WebUSB bindings for the `openipc-rs` receiver stack.
+
+This package is the browser SDK layer. It exposes the Rust OpenIPC transport
+pipeline to JavaScript:
+
+- Realtek USB RX transfer parsing
+- WFB session/decryption/FEC handling
+- RTP depacketization
+- H.264/H.265 Annex-B frame output for WebCodecs
+- Adaptive-link feedback helpers
+- WebUSB Realtek device access
+
+It does not include a UI or video renderer. Applications are expected to feed
+the encoded frames into WebCodecs, MSE, a worker pipeline, or another renderer.
+
+## Install
+
+```sh
+npm install @openipc-rs/web
+```
+
+## Basic Shape
+
+```ts
+import init, {
+  OpenIpcReceiver,
+  WebUsbRealtekDevice,
+  supportedUsbFilters,
+} from "@openipc-rs/web";
+
+await init();
+
+const filters = JSON.parse(supportedUsbFilters());
+const usbDevice = await navigator.usb.requestDevice({ filters });
+const radio = await WebUsbRealtekDevice.fromWebUsbDevice(usbDevice);
+const receiver = OpenIpcReceiver.withKeypair(channelId, keypairBytes, minimumEpoch);
+
+await radio.initializeMonitor(channel, channelWidthMhz, channelOffset);
+
+while (running) {
+  const transfer = await radio.readRxTransfer(32768);
+  const batch = receiver.pushRxTransferProfiled(transfer);
+  for (const frame of batch.frames) {
+    // frame.data is encoded H.264/H.265 Annex-B data.
+    // Feed it into WebCodecs as an EncodedVideoChunk.
+  }
+}
+```
+
+## WebCodecs Rendering
+
+The Rust/WASM side outputs compressed H.264/H.265 frames. Your app should pass
+those frames to WebCodecs and render the decoded `VideoFrame` objects.
+
+```html
+<canvas id="video"></canvas>
+```
+
+```ts
+import init, {
+  OpenIpcReceiver,
+  WebUsbRealtekDevice,
+  supportedUsbFilters,
+  type OpenIpcVideoFrame,
+} from "@openipc-rs/web";
+
+const canvas = document.querySelector<HTMLCanvasElement>("#video")!;
+const ctx = canvas.getContext("2d", { alpha: false })!;
+
+let decoder: VideoDecoder | undefined;
+let decoderKey = "";
+let waitingForKeyframe = true;
+let baseRtpTimestamp: number | undefined;
+let baseTimestampUs = 0;
+
+function timestampUs(rtpTimestamp: number): number {
+  if (baseRtpTimestamp === undefined) {
+    baseRtpTimestamp = rtpTimestamp >>> 0;
+    baseTimestampUs = Math.round(performance.now() * 1000);
+  }
+
+  const delta = (rtpTimestamp >>> 0) - baseRtpTimestamp;
+  return baseTimestampUs + Math.round((delta * 1_000_000) / 90_000);
+}
+
+function renderFrame(frame: VideoFrame) {
+  try {
+    const width = frame.displayWidth || frame.codedWidth;
+    const height = frame.displayHeight || frame.codedHeight;
+    if (canvas.width !== width || canvas.height !== height) {
+      canvas.width = width;
+      canvas.height = height;
+    }
+    ctx.drawImage(frame, 0, 0, width, height);
+  } finally {
+    frame.close();
+  }
+}
+
+async function ensureDecoder(frame: OpenIpcVideoFrame): Promise<boolean> {
+  const codec = frame.codecString;
+  const key = `${frame.codec}:${codec}`;
+  if (decoder && decoderKey === key) {
+    return true;
+  }
+
+  const config: VideoDecoderConfig =
+    frame.codec === "h264"
+      ? { codec, avc: { format: "annexb" }, hardwareAcceleration: "prefer-hardware", optimizeForLatency: true }
+      : { codec, hevc: { format: "annexb" }, hardwareAcceleration: "prefer-hardware", optimizeForLatency: true };
+
+  const support = await VideoDecoder.isConfigSupported(config);
+  if (!support.supported) {
+    return false;
+  }
+
+  decoder?.close();
+  decoder = new VideoDecoder({
+    output: renderFrame,
+    error: (error) => {
+      console.warn("VideoDecoder error", error);
+      waitingForKeyframe = true;
+    },
+  });
+  decoder.configure(support.config ?? config);
+  decoderKey = key;
+  waitingForKeyframe = true;
+  return true;
+}
+
+async function decodeOpenIpcFrame(frame: OpenIpcVideoFrame) {
+  if (!(await ensureDecoder(frame))) {
+    return;
+  }
+  if (waitingForKeyframe && !frame.isKeyFrame) {
+    return;
+  }
+
+  waitingForKeyframe = false;
+  decoder!.decode(
+    new EncodedVideoChunk({
+      type: frame.isKeyFrame ? "key" : "delta",
+      timestamp: timestampUs(frame.timestamp),
+      data: frame.data,
+    }),
+  );
+}
+
+await init();
+
+const filters = JSON.parse(supportedUsbFilters());
+const usbDevice = await navigator.usb.requestDevice({ filters });
+const radio = await WebUsbRealtekDevice.fromWebUsbDevice(usbDevice);
+const receiver = OpenIpcReceiver.withKeypair(channelId, keypairBytes, minimumEpoch);
+
+await radio.initializeMonitor(channel, channelWidthMhz, channelOffset);
+
+while (running) {
+  const transfer = await radio.readRxTransfer(32768);
+  const batch = receiver.pushRxTransferProfiled(transfer);
+  for (const frame of batch.frames) {
+    await decodeOpenIpcFrame(frame);
+  }
+}
+```
+
+## Browser Requirements
+
+- HTTPS or localhost secure context
+- WebUSB support
+- WebCodecs support for playback in typical browser apps
+- A supported Realtek 802.11ac USB adapter
+
+## Build From Source
+
+From the repository root:
+
+```sh
+npm --prefix crates/openipc-web run build
+```
+
+The build generates the publishable package in:
+
+```text
+crates/openipc-web/pkg
+```
+
+Generated files are not committed to Git.

package/openipc_web.d.ts

@@ -0,0 +1,168 @@
+/* tslint:disable */
+/* eslint-disable */
+
+export type OpenIpcVideoFrame = {
+    data: Uint8Array;
+    codec: "h264" | "h265";
+    codecString: string;
+    isKeyFrame: boolean;
+    timestamp: number;
+};
+
+export type OpenIpcRxTransferProfile = {
+    frames: OpenIpcVideoFrame[];
+    transferBytes: number;
+    packets: number;
+    acceptedPackets: number;
+    droppedPackets: number;
+    crcDropped: number;
+    icvDropped: number;
+    reportDropped: number;
+    ignoredFrames: number;
+    sessions: number;
+    wfbPayloads: number;
+    rtpPackets: number;
+    videoFrames: number;
+    parseMs: number;
+    pipelineMs: number;
+    totalMs: number;
+};
+
+
+
+export class OpenIpcAdaptiveLink {
+    free(): void;
+    [Symbol.dispose](): void;
+    counters(): string;
+    constructor(link_id: number, keypair: Uint8Array, epoch: bigint, fec_k: number, fec_n: number);
+    quality(now_ms: number): string;
+    recordFec(now_ms: number, total: number, recovered: number, lost: number): void;
+    recordReceiverCounters(receiver: OpenIpcReceiver, now_ms: number): void;
+    recordRx(now_ms: number, rssi0: number, rssi1: number, snr0: number, snr1: number): void;
+    recordRxTransfer(transfer: Uint8Array, now_ms: number): void;
+    requestKeyframe(): void;
+    setKeyframeRequestMessages(messages: number): void;
+    setVideoStartIdleMs(idle_ms: number): void;
+    tick(now_ms: number): Array<any>;
+    tickAndSend(device: WebUsbRealtekDevice, now_ms: number, current_channel: number): Promise<number>;
+}
+
+export class OpenIpcReceiver {
+    free(): void;
+    [Symbol.dispose](): void;
+    fecCounters(): string;
+    constructor();
+    pushDecrypted80211Frame(frame: Uint8Array, fragment: Uint8Array): Array<any>;
+    pushDecryptedFragment(data_nonce_hex: string, fragment: Uint8Array): Array<any>;
+    pushEncrypted80211Frame(frame: Uint8Array): Array<any>;
+    pushRtpPacket(data: Uint8Array): Uint8Array | undefined;
+    pushRtpPacketDetailed(data: Uint8Array): OpenIpcVideoFrame | null;
+    pushRxTransfer(transfer: Uint8Array): Array<any>;
+    pushRxTransferDetailed(transfer: Uint8Array): OpenIpcVideoFrame[];
+    pushRxTransferProfiled(transfer: Uint8Array): OpenIpcRxTransferProfile;
+    static withChannelId(channel_id: number, fec_k: number, fec_n: number): OpenIpcReceiver;
+    static withKeypair(channel_id: number, keypair: Uint8Array, minimum_epoch: bigint): OpenIpcReceiver;
+}
+
+export class WebUsbRealtekDevice {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    bulkInEndpoint(): number;
+    bulkOutEndpoint(): number;
+    static fromWebUsbDevice(device: USBDevice): Promise<WebUsbRealtekDevice>;
+    initializeMonitor(channel: number, channel_width_mhz: number, channel_offset: number): Promise<string>;
+    readRegisterU32(register: number): Promise<number>;
+    readRegisterU8(register: number): Promise<number>;
+    readRxTransfer(length: number): Promise<Uint8Array>;
+    sendPacket(radiotap_packet: Uint8Array, current_channel: number): Promise<number>;
+    setTxPowerOverride(current_channel: number, power: number): Promise<void>;
+    writeTxTransfer(transfer: Uint8Array): Promise<number>;
+}
+
+export function listAuthorizedUsbDevices(): Promise<Array<any>>;
+
+export function supportedUsbFilters(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_openipcadaptivelink_free: (a: number, b: number) => void;
+    readonly __wbg_openipcreceiver_free: (a: number, b: number) => void;
+    readonly __wbg_webusbrealtekdevice_free: (a: number, b: number) => void;
+    readonly listAuthorizedUsbDevices: () => any;
+    readonly openipcadaptivelink_counters: (a: number) => [number, number];
+    readonly openipcadaptivelink_new: (a: number, b: number, c: number, d: bigint, e: number, f: number) => [number, number, number];
+    readonly openipcadaptivelink_quality: (a: number, b: number) => [number, number];
+    readonly openipcadaptivelink_recordFec: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly openipcadaptivelink_recordReceiverCounters: (a: number, b: number, c: number) => void;
+    readonly openipcadaptivelink_recordRx: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
+    readonly openipcadaptivelink_recordRxTransfer: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly openipcadaptivelink_requestKeyframe: (a: number) => void;
+    readonly openipcadaptivelink_setKeyframeRequestMessages: (a: number, b: number) => void;
+    readonly openipcadaptivelink_setVideoStartIdleMs: (a: number, b: number) => void;
+    readonly openipcadaptivelink_tick: (a: number, b: number) => [number, number, number];
+    readonly openipcadaptivelink_tickAndSend: (a: number, b: number, c: number, d: number) => any;
+    readonly openipcreceiver_fecCounters: (a: number) => [number, number];
+    readonly openipcreceiver_new: () => [number, number, number];
+    readonly openipcreceiver_pushDecrypted80211Frame: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly openipcreceiver_pushDecryptedFragment: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
+    readonly openipcreceiver_pushEncrypted80211Frame: (a: number, b: number, c: number) => [number, number, number];
+    readonly openipcreceiver_pushRtpPacket: (a: number, b: number, c: number) => any;
+    readonly openipcreceiver_pushRtpPacketDetailed: (a: number, b: number, c: number) => [number, number, number];
+    readonly openipcreceiver_pushRxTransfer: (a: number, b: number, c: number) => [number, number, number];
+    readonly openipcreceiver_pushRxTransferDetailed: (a: number, b: number, c: number) => [number, number, number];
+    readonly openipcreceiver_pushRxTransferProfiled: (a: number, b: number, c: number) => [number, number, number];
+    readonly openipcreceiver_withChannelId: (a: number, b: number, c: number) => [number, number, number];
+    readonly openipcreceiver_withKeypair: (a: number, b: number, c: number, d: bigint) => [number, number, number];
+    readonly supportedUsbFilters: () => [number, number];
+    readonly webusbrealtekdevice_bulkInEndpoint: (a: number) => number;
+    readonly webusbrealtekdevice_bulkOutEndpoint: (a: number) => number;
+    readonly webusbrealtekdevice_fromWebUsbDevice: (a: any) => any;
+    readonly webusbrealtekdevice_initializeMonitor: (a: number, b: number, c: number, d: number) => any;
+    readonly webusbrealtekdevice_readRegisterU32: (a: number, b: number) => any;
+    readonly webusbrealtekdevice_readRegisterU8: (a: number, b: number) => any;
+    readonly webusbrealtekdevice_readRxTransfer: (a: number, b: number) => any;
+    readonly webusbrealtekdevice_sendPacket: (a: number, b: number, c: number, d: number) => any;
+    readonly webusbrealtekdevice_setTxPowerOverride: (a: number, b: number, c: number) => any;
+    readonly webusbrealtekdevice_writeTxTransfer: (a: number, b: number, c: number) => any;
+    readonly wasm_bindgen__convert__closures_____invoke__h39fee390da28f45f: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h35992852bc42cc91: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h22e0fe300bd7dd70: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h35992852bc42cc91_3: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h35992852bc42cc91_4: (a: number, b: number, c: any) => [number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h32085c8bafd70877: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h4d860cdb1981635b: (a: number, b: number) => void;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;