@qvac/sdk 0.18.2 → 0.19.0

package/dist/src/client/api/upscale.js

@@ -0,0 +1,99 @@
+import { upscaleStreamResponseSchema } from '@qvac/inference/surface';
+import { stream as streamRpc } from '../rpc/rpc-client.js';
+import { decodeBase64, encodeBase64 } from '../../utils/encoding.js';
+import { StreamEndedError } from '../../utils/errors-client.js';
+/**
+ * Runs standalone ESRGAN upscaling on an arbitrary PNG/JPEG image.
+ *
+ * The model must have been loaded with `modelType: "diffusion"` and
+ * `modelConfig.mode: "upscale"` — calling `upscale()` against a model
+ * loaded in default (`mode: "diffusion"`) mode throws
+ * `ModelOperationNotSupportedError` upfront.
+ *
+ * `outputs` always resolves to length 1: `repeats` runs N passes
+ * internally and emits a single final image at `source * scale^repeats`
+ * dimensions. The `Uint8Array[]` shape reserves headroom for future
+ * multi-output variants.
+ *
+ * @param params - `{ modelId, image, repeats? }`. `image` is raw PNG/JPEG
+ *   bytes; the client base64-encodes them on the wire.
+ * @returns `{ outputs, stats }` — `outputs` resolves to a single-element
+ *   array containing the final upscaled PNG; `stats` resolves to
+ *   addon-side stats (load/upscale ms, final width/height, repeats
+ *   actually executed, etc.).
+ * @throws {ModelOperationNotSupportedError} If the model was not loaded
+ *   with `mode: "upscale"`.
+ * @throws {StreamEndedError} If the RPC stream closes without emitting a
+ *   terminal `done` chunk.
+ *
+ * @example
+ * ```ts
+ * const modelId = await loadModel(REALESRGAN_X4PLUS_ANIME_6B, {
+ *   modelType: "diffusion",
+ *   modelConfig: { mode: "upscale", upscaler: { tile_size: 128 } },
+ * });
+ * const pngBytes = fs.readFileSync("input.png");
+ * const { outputs, stats } = upscale({ modelId, image: pngBytes, repeats: 2 });
+ * const [upscaledPng] = await outputs;
+ * fs.writeFileSync("upscaled.png", upscaledPng);
+ * console.log(await stats);
+ * ```
+ */
+export function upscale(params) {
+    const request = {
+        modelId: params.modelId,
+        image: encodeBase64(params.image),
+        ...(params.repeats !== undefined && { repeats: params.repeats }),
+        type: 'upscaleStream'
+    };
+    let statsResolver = () => { };
+    let statsRejecter = () => { };
+    const statsPromise = new Promise((resolve, reject) => {
+        statsResolver = resolve;
+        statsRejecter = reject;
+    });
+    statsPromise.catch(() => { });
+    let outputsResolver = () => { };
+    let outputsRejecter = () => { };
+    const outputsPromise = new Promise((resolve, reject) => {
+        outputsResolver = resolve;
+        outputsRejecter = reject;
+    });
+    outputsPromise.catch(() => { });
+    const collectedBuffers = [];
+    async function processResponses() {
+        let sawDone = false;
+        try {
+            for await (const response of streamRpc(request)) {
+                if (response &&
+                    typeof response === 'object' &&
+                    'type' in response &&
+                    response.type === 'upscaleStream') {
+                    const parsed = upscaleStreamResponseSchema.parse(response);
+                    if (parsed.data) {
+                        collectedBuffers.push(decodeBase64(parsed.data));
+                    }
+                    if (parsed.done) {
+                        sawDone = true;
+                        statsResolver(parsed.stats);
+                        outputsResolver(collectedBuffers);
+                    }
+                }
+            }
+            if (!sawDone) {
+                const error = new StreamEndedError();
+                statsRejecter(error);
+                outputsRejecter(error);
+            }
+        }
+        catch (error) {
+            statsRejecter(error);
+            outputsRejecter(error);
+        }
+    }
+    void processResponses();
+    return {
+        outputs: outputsPromise,
+        stats: statsPromise
+    };
+}

package/dist/src/client/api/video-request.d.ts

@@ -0,0 +1,208 @@
+import type { VideoClientParams } from '@qvac/inference/surface';
+export declare function createVideoStreamRequest(params: VideoClientParams, requestId: string): {
+    type: "videoStream";
+    requestId: string;
+    reference_images?: string[];
+    init_image?: string;
+    control_frames?: string[];
+    prompt: string;
+    modelId: string;
+    seed?: number | undefined;
+    vae_tiling?: boolean | undefined;
+    negative_prompt?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    steps?: number | undefined;
+    cfg_scale?: number | undefined;
+    sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
+    cache_preset?: string | undefined;
+    stg_scale?: number | undefined;
+    stg_block?: number | undefined;
+    video_frames?: number | undefined;
+    fps?: number | undefined;
+    flow_shift?: number | undefined;
+    high_noise_steps?: number | undefined;
+    high_noise_sampler?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    high_noise_scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | undefined;
+    high_noise_cfg_scale?: number | undefined;
+    high_noise_flow_shift?: number | undefined;
+    moe_boundary?: number | undefined;
+    vace_strength?: number | undefined;
+    vae_tile_size?: string | number | undefined;
+    vae_tile_overlap?: number | undefined;
+    temporal_tiling?: boolean | undefined;
+    cache_mode?: "disabled" | "easycache" | "ucache" | "dbcache" | "taylorseer" | "cache-dit" | undefined;
+    cache_threshold?: number | undefined;
+    lora?: never;
+    lora_strength?: never;
+    mode: "txt2vid";
+    strength?: never;
+    reference_attention_strength?: never;
+    reference_downscale_factor?: never;
+} | {
+    type: "videoStream";
+    requestId: string;
+    reference_images?: string[];
+    init_image?: string;
+    control_frames?: string[];
+    prompt: string;
+    modelId: string;
+    seed?: number | undefined;
+    vae_tiling?: boolean | undefined;
+    negative_prompt?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    steps?: number | undefined;
+    cfg_scale?: number | undefined;
+    sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
+    cache_preset?: string | undefined;
+    stg_scale?: number | undefined;
+    stg_block?: number | undefined;
+    video_frames?: number | undefined;
+    fps?: number | undefined;
+    flow_shift?: number | undefined;
+    high_noise_steps?: number | undefined;
+    high_noise_sampler?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    high_noise_scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | undefined;
+    high_noise_cfg_scale?: number | undefined;
+    high_noise_flow_shift?: number | undefined;
+    moe_boundary?: number | undefined;
+    vace_strength?: number | undefined;
+    vae_tile_size?: string | number | undefined;
+    vae_tile_overlap?: number | undefined;
+    temporal_tiling?: boolean | undefined;
+    cache_mode?: "disabled" | "easycache" | "ucache" | "dbcache" | "taylorseer" | "cache-dit" | undefined;
+    cache_threshold?: number | undefined;
+    lora: string;
+    lora_strength?: number;
+    mode: "txt2vid";
+    strength?: never;
+    reference_attention_strength?: never;
+    reference_downscale_factor?: never;
+} | {
+    type: "videoStream";
+    requestId: string;
+    reference_images?: string[];
+    init_image?: string;
+    control_frames?: string[];
+    prompt: string;
+    modelId: string;
+    seed?: number | undefined;
+    vae_tiling?: boolean | undefined;
+    negative_prompt?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    steps?: number | undefined;
+    cfg_scale?: number | undefined;
+    sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
+    cache_preset?: string | undefined;
+    stg_scale?: number | undefined;
+    stg_block?: number | undefined;
+    video_frames: number;
+    fps?: number | undefined;
+    flow_shift?: number | undefined;
+    high_noise_steps?: number | undefined;
+    high_noise_sampler?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    high_noise_scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | undefined;
+    high_noise_cfg_scale?: number | undefined;
+    high_noise_flow_shift?: number | undefined;
+    moe_boundary?: number | undefined;
+    vace_strength?: number | undefined;
+    vae_tile_size?: string | number | undefined;
+    vae_tile_overlap?: number | undefined;
+    temporal_tiling?: boolean | undefined;
+    cache_mode?: "disabled" | "easycache" | "ucache" | "dbcache" | "taylorseer" | "cache-dit" | undefined;
+    cache_threshold?: number | undefined;
+    mode: "txt2vid";
+    strength?: never;
+    lora: string;
+    lora_strength?: number;
+    reference_attention_strength?: number;
+    reference_downscale_factor?: 1;
+} | {
+    type: "videoStream";
+    requestId: string;
+    reference_images?: string[];
+    init_image?: string;
+    control_frames?: string[];
+    prompt: string;
+    modelId: string;
+    seed?: number | undefined;
+    vae_tiling?: boolean | undefined;
+    negative_prompt?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    steps?: number | undefined;
+    cfg_scale?: number | undefined;
+    sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
+    cache_preset?: string | undefined;
+    stg_scale?: number | undefined;
+    stg_block?: number | undefined;
+    video_frames?: number | undefined;
+    fps?: number | undefined;
+    flow_shift?: number | undefined;
+    high_noise_steps?: number | undefined;
+    high_noise_sampler?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    high_noise_scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | undefined;
+    high_noise_cfg_scale?: number | undefined;
+    high_noise_flow_shift?: number | undefined;
+    moe_boundary?: number | undefined;
+    vace_strength?: number | undefined;
+    vae_tile_size?: string | number | undefined;
+    vae_tile_overlap?: number | undefined;
+    temporal_tiling?: boolean | undefined;
+    cache_mode?: "disabled" | "easycache" | "ucache" | "dbcache" | "taylorseer" | "cache-dit" | undefined;
+    cache_threshold?: number | undefined;
+    lora?: never;
+    lora_strength?: never;
+    mode: "img2vid";
+    strength?: number;
+    reference_attention_strength?: never;
+    reference_downscale_factor?: never;
+} | {
+    type: "videoStream";
+    requestId: string;
+    reference_images?: string[];
+    init_image?: string;
+    control_frames?: string[];
+    prompt: string;
+    modelId: string;
+    seed?: number | undefined;
+    vae_tiling?: boolean | undefined;
+    negative_prompt?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    steps?: number | undefined;
+    cfg_scale?: number | undefined;
+    sampling_method?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | "ltx2" | undefined;
+    cache_preset?: string | undefined;
+    stg_scale?: number | undefined;
+    stg_block?: number | undefined;
+    video_frames?: number | undefined;
+    fps?: number | undefined;
+    flow_shift?: number | undefined;
+    high_noise_steps?: number | undefined;
+    high_noise_sampler?: "euler" | "euler_a" | "heun" | "dpm2" | "dpm++2m" | "dpm++2mv2" | "dpm++2s_a" | "lcm" | "ipndm" | "ipndm_v" | "ddim_trailing" | "tcd" | "res_multistep" | "res_2s" | undefined;
+    high_noise_scheduler?: "lcm" | "discrete" | "karras" | "exponential" | "ays" | "gits" | "sgm_uniform" | "simple" | "smoothstep" | "kl_optimal" | "bong_tangent" | undefined;
+    high_noise_cfg_scale?: number | undefined;
+    high_noise_flow_shift?: number | undefined;
+    moe_boundary?: number | undefined;
+    vace_strength?: number | undefined;
+    vae_tile_size?: string | number | undefined;
+    vae_tile_overlap?: number | undefined;
+    temporal_tiling?: boolean | undefined;
+    cache_mode?: "disabled" | "easycache" | "ucache" | "dbcache" | "taylorseer" | "cache-dit" | undefined;
+    cache_threshold?: number | undefined;
+    lora: string;
+    lora_strength?: number;
+    mode: "img2vid";
+    strength?: number;
+    reference_attention_strength?: never;
+    reference_downscale_factor?: never;
+};
+//# sourceMappingURL=video-request.d.ts.map

package/dist/src/client/api/video-request.js

@@ -0,0 +1,18 @@
+import { encodeBase64 } from '../../utils/encoding.js';
+export function createVideoStreamRequest(params, requestId) {
+    const { control_frames, init_image, reference_images, ...rest } = params;
+    return {
+        ...rest,
+        ...(control_frames !== undefined && {
+            control_frames: control_frames.map(encodeBase64)
+        }),
+        ...(init_image !== undefined && {
+            init_image: encodeBase64(init_image)
+        }),
+        ...(reference_images !== undefined && {
+            reference_images: reference_images.map(encodeBase64)
+        }),
+        type: 'videoStream',
+        requestId
+    };
+}

package/dist/src/client/api/video.d.ts

@@ -0,0 +1,107 @@
+import { type VideoClientParams, type VideoStats } from '@qvac/inference/surface';
+export interface VideoProgressTick {
+    step: number;
+    totalSteps: number;
+    elapsedMs: number;
+}
+export interface VideoResult {
+    requestId: string;
+    progressStream: AsyncGenerator<VideoProgressTick>;
+    outputs: Promise<Uint8Array[]>;
+    stats: Promise<VideoStats | undefined>;
+}
+/**
+ * Generates a video using a loaded video diffusion model.
+ *
+ * @param params - Video request parameters (model, prompt, dimensions, frame count, fps, sampler, seed, etc.).
+ * @returns A result object exposing `requestId` (stable identifier for this in-flight generation), `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated video buffers, typically a single AVI file), and `stats` (promise of generation statistics).
+ *
+ * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video) for both the
+ * Wan and LTX-2 layouts. For Wan `img2vid`, load the pipeline with
+ * `modelConfig.clipVisionModelSrc` set to `clip_vision_h.safetensors`; LTX-2
+ * `img2vid` conditions on the first frame through its video VAE and needs no
+ * CLIP vision weights (the same LTX-2 model loaded for txt2vid also does
+ * img2vid). On React Native, the bundled video diffusion models are too large
+ * for typical mobile devices.
+ *
+ * @example Basic txt2vid generation
+ * ```typescript
+ * const { outputs, stats } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a cat surfing a wave at sunset",
+ *   width: 480,
+ *   height: 832,
+ *   video_frames: 17, // must satisfy (4*k + 1)
+ *   fps: 16,
+ * });
+ * const buffers = await outputs;
+ * fs.writeFileSync("output.avi", buffers[0]);
+ * ```
+ *
+ * @example With progress tracking
+ * ```typescript
+ * const { progressStream, outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a sunset over the ocean",
+ * });
+ * for await (const { step, totalSteps } of progressStream) {
+ *   console.log(`${step}/${totalSteps}`);
+ * }
+ * const buffers = await outputs;
+ * ```
+ *
+ * @example Image-to-video (first frame + motion prompt)
+ * ```typescript
+ * const firstFrame = fs.readFileSync("portrait.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "img2vid",
+ *   prompt: "the subject slowly turns and smiles, cinematic lighting",
+ *   init_image: firstFrame,
+ *   strength: 0.85,
+ * });
+ * ```
+ *
+ * @example With control frames (e.g. for guided generation)
+ * ```typescript
+ * const frameA = fs.readFileSync("frame-a.png");
+ * const frameB = fs.readFileSync("frame-b.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "smooth transition between scenes",
+ *   control_frames: [frameA, frameB],
+ * });
+ * ```
+ *
+ * @example LTX Ingredients reference conditioning
+ * ```typescript
+ * const referenceSheet = fs.readFileSync("reference-sheet.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "Reference sheet: a red-haired explorer. Generated video: the explorer crosses a snowy ridge.",
+ *   lora: "/absolute/path/to/ltx-2-ingredients.safetensors",
+ *   lora_strength: 1.37,
+ *   stg_scale: 1,
+ *   stg_block: 29,
+ *   reference_images: [referenceSheet],
+ *   reference_attention_strength: 1,
+ *   reference_downscale_factor: 1,
+ *   video_frames: 217,
+ *   scheduler: "ltx2",
+ * });
+ * const buffers = await outputs;
+ * ```
+ *
+ * @example Cancellation via requestId
+ * ```typescript
+ * const { requestId, outputs } = video({ modelId, mode: "txt2vid", prompt: "..." });
+ * // ...later
+ * await cancel(requestId);
+ * ```
+ */
+export declare function video(params: VideoClientParams): VideoResult;
+//# sourceMappingURL=video.d.ts.map

package/dist/src/client/api/video.js

@@ -0,0 +1,187 @@
+import { videoStreamResponseSchema } from '@qvac/inference/surface';
+import { stream as streamRpc } from '../rpc/rpc-client.js';
+import { generateClientRequestId } from './client-request-id.js';
+import { createVideoStreamRequest } from './video-request.js';
+import { decodeBase64 } from '../../utils/encoding.js';
+/**
+ * Generates a video using a loaded video diffusion model.
+ *
+ * @param params - Video request parameters (model, prompt, dimensions, frame count, fps, sampler, seed, etc.).
+ * @returns A result object exposing `requestId` (stable identifier for this in-flight generation), `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated video buffers, typically a single AVI file), and `stats` (promise of generation statistics).
+ *
+ * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video) for both the
+ * Wan and LTX-2 layouts. For Wan `img2vid`, load the pipeline with
+ * `modelConfig.clipVisionModelSrc` set to `clip_vision_h.safetensors`; LTX-2
+ * `img2vid` conditions on the first frame through its video VAE and needs no
+ * CLIP vision weights (the same LTX-2 model loaded for txt2vid also does
+ * img2vid). On React Native, the bundled video diffusion models are too large
+ * for typical mobile devices.
+ *
+ * @example Basic txt2vid generation
+ * ```typescript
+ * const { outputs, stats } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a cat surfing a wave at sunset",
+ *   width: 480,
+ *   height: 832,
+ *   video_frames: 17, // must satisfy (4*k + 1)
+ *   fps: 16,
+ * });
+ * const buffers = await outputs;
+ * fs.writeFileSync("output.avi", buffers[0]);
+ * ```
+ *
+ * @example With progress tracking
+ * ```typescript
+ * const { progressStream, outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a sunset over the ocean",
+ * });
+ * for await (const { step, totalSteps } of progressStream) {
+ *   console.log(`${step}/${totalSteps}`);
+ * }
+ * const buffers = await outputs;
+ * ```
+ *
+ * @example Image-to-video (first frame + motion prompt)
+ * ```typescript
+ * const firstFrame = fs.readFileSync("portrait.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "img2vid",
+ *   prompt: "the subject slowly turns and smiles, cinematic lighting",
+ *   init_image: firstFrame,
+ *   strength: 0.85,
+ * });
+ * ```
+ *
+ * @example With control frames (e.g. for guided generation)
+ * ```typescript
+ * const frameA = fs.readFileSync("frame-a.png");
+ * const frameB = fs.readFileSync("frame-b.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "smooth transition between scenes",
+ *   control_frames: [frameA, frameB],
+ * });
+ * ```
+ *
+ * @example LTX Ingredients reference conditioning
+ * ```typescript
+ * const referenceSheet = fs.readFileSync("reference-sheet.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "Reference sheet: a red-haired explorer. Generated video: the explorer crosses a snowy ridge.",
+ *   lora: "/absolute/path/to/ltx-2-ingredients.safetensors",
+ *   lora_strength: 1.37,
+ *   stg_scale: 1,
+ *   stg_block: 29,
+ *   reference_images: [referenceSheet],
+ *   reference_attention_strength: 1,
+ *   reference_downscale_factor: 1,
+ *   video_frames: 217,
+ *   scheduler: "ltx2",
+ * });
+ * const buffers = await outputs;
+ * ```
+ *
+ * @example Cancellation via requestId
+ * ```typescript
+ * const { requestId, outputs } = video({ modelId, mode: "txt2vid", prompt: "..." });
+ * // ...later
+ * await cancel(requestId);
+ * ```
+ */
+export function video(params) {
+    const requestId = generateClientRequestId();
+    const request = createVideoStreamRequest(params, requestId);
+    let statsResolver = () => { };
+    let statsRejecter = () => { };
+    const statsPromise = new Promise((resolve, reject) => {
+        statsResolver = resolve;
+        statsRejecter = reject;
+    });
+    statsPromise.catch(() => { });
+    const progressQueue = [];
+    const collectedBuffers = [];
+    let progressDone = false;
+    let progressResolve = null;
+    let streamError = null;
+    let outputsResolver = () => { };
+    let outputsRejecter = () => { };
+    const outputsPromise = new Promise((resolve, reject) => {
+        outputsResolver = resolve;
+        outputsRejecter = reject;
+    });
+    outputsPromise.catch(() => { });
+    async function processResponses() {
+        try {
+            for await (const response of streamRpc(request)) {
+                if (response &&
+                    typeof response === 'object' &&
+                    'type' in response &&
+                    response.type === 'videoStream') {
+                    const parsed = videoStreamResponseSchema.parse(response);
+                    if (parsed.step !== undefined &&
+                        parsed.totalSteps !== undefined &&
+                        parsed.elapsedMs !== undefined) {
+                        progressQueue.push({
+                            step: parsed.step,
+                            totalSteps: parsed.totalSteps,
+                            elapsedMs: parsed.elapsedMs
+                        });
+                        if (progressResolve) {
+                            progressResolve();
+                            progressResolve = null;
+                        }
+                    }
+                    if (parsed.data) {
+                        collectedBuffers.push(decodeBase64(parsed.data));
+                    }
+                    if (parsed.done) {
+                        statsResolver(parsed.stats);
+                        outputsResolver(collectedBuffers);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            streamError = error instanceof Error ? error : new Error(String(error));
+            statsRejecter(streamError);
+            outputsRejecter(streamError);
+        }
+        progressDone = true;
+        if (progressResolve) {
+            progressResolve();
+            progressResolve = null;
+        }
+    }
+    void processResponses();
+    const progressStream = (async function* () {
+        while (true) {
+            if (progressQueue.length > 0) {
+                yield progressQueue.shift();
+            }
+            else if (progressDone) {
+                if (streamError)
+                    throw streamError;
+                return;
+            }
+            else {
+                await new Promise((resolve) => {
+                    progressResolve = resolve;
+                });
+            }
+        }
+    })();
+    return {
+        requestId,
+        progressStream,
+        outputs: outputsPromise,
+        stats: statsPromise
+    };
+}

package/dist/src/client/api/vla-helpers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Pure-JS helpers for preparing VLA inference inputs on the client side.
+ *
+ * Mirrors `preprocessImage` / `padState` / `DEFAULT_IMAGE_SIZE` from
+ * `@qvac/vla-ggml/addon.js`. Kept inlined (not re-exported from the addon)
+ * so the SDK's client surface never loads the addon's native binding —
+ * consumers running under Node / Bun / Expo without VLA prebuilds can still
+ * use the SDK to drive a remote VLA worker.
+ *
+ * This file is a verbatim port of the addon's JS implementation; keep them
+ * in sync so the wire-format tensors stay byte-identical regardless of
+ * where preprocessing runs (consumer process vs worker vs addon).
+ */
+/** Default vision tower image size used by SmolVLA-LIBERO. */
+export declare const VLA_DEFAULT_IMAGE_SIZE = 512;
+type PixelsInput = Float32Array | Uint8Array | number[];
+type ImageLayout = 'hwc' | 'chw';
+export interface VlaPreprocessImageOptions {
+    size?: number;
+    layout?: ImageLayout;
+    /**
+     * Skip the [0,255] vs [0,1] auto-detection heuristic when the caller knows
+     * the range. `1` = pixels already in [0,1] (no rescale). `1/255` = pixels
+     * in [0,255] (rescale to [0,1]). Any other value (including the literal
+     * `'auto'`) falls back to the heuristic.
+     */
+    scale?: number | 'auto';
+}
+/**
+ * Resize + letterbox + normalize a camera frame to `(3, size, size)` Float32
+ * in `[-1, 1]`. Drop-in equivalent of `@qvac/vla-ggml`'s `preprocessImage`.
+ *
+ * Letterbox places the resized content at the **bottom-right** with padding
+ * at top/left (`padLeft = size - newW`, `padTop = size - newH`), matching
+ * the reference smolvla.cpp behavior.
+ *
+ * @param pixels - RGB pixel values in HWC or CHW layout.
+ * @param width - Source image width in pixels.
+ * @param height - Source image height in pixels.
+ * @param opts - Target size, source layout, and optional input-range scale.
+ * @returns A normalized CHW tensor with shape `(3, size, size)`.
+ * @throws {TypeError} When width or height is not a positive integer.
+ * @throws {RangeError} When the pixel count does not match the dimensions.
+ */
+export declare function vlaPreprocessImage(pixels: PixelsInput, width: number, height: number, opts?: VlaPreprocessImageOptions): Float32Array;
+/**
+ * Zero-pad a state vector to `targetDim`. Extra entries are zero-initialised;
+ * input longer than `targetDim` raises. Mirrors how smolvla.cpp expects the
+ * state tensor (`max_state_dim` = 32 by default).
+ *
+ * @param state - Robot state values to copy into the padded tensor.
+ * @param targetDim - Required output dimension (default: 32).
+ * @returns A `Float32Array` of exactly `targetDim` values.
+ * @throws {TypeError} When `targetDim` is not a positive integer.
+ * @throws {RangeError} When `state` is longer than `targetDim`.
+ */
+export declare function vlaPadState(state: ArrayLike<number>, targetDim?: number): Float32Array;
+export {};
+//# sourceMappingURL=vla-helpers.d.ts.map