客户端解码 SDK

在浏览器中直接解码隐写或加密的生成内容

我们的生成 API 返回的某些结果（如 AI 生成的图像）可能内部隐藏或加密了视频等内容。为了查看这些内容，用户不需要将文件重新传回我们的服务器进行解析。

为此，我们提供了一个强大的纯客户端解码 SDK (qxan-decoder-sdk)。它完全在用户的浏览器前端运行，不仅保护了用户隐私，还能节省服务器带宽并提供即时的播放体验。

安装

你可以通过 npm 或 pnpm 安装此 SDK：

npm install qxan-decoder-sdk
# 或
pnpm add qxan-decoder-sdk

快速开始 (SS_tools 示例)

以下是如何使用 SSDecoder 从图像文件中提取帧或视频的典型示例。

import { SSDecoder } from "qxan-decoder-sdk";

// 'imageFile' 是通过用户上传或从 API 结果 URL fetch 到的 File/Blob 对象
const result = await SSDecoder.decode(
  imageFile,
  "optional-password", // 可选的解密密码
  {
    expect: "image", // 对于 binpng 格式可提取帧 ('image')，或直接提取视频 ('video')
    maxFrames: 8,
    onProgress: (msg) => console.log("[SS 解码进度]:", msg),
  }
);

if (result.type === "video") {
  // result.videoUrl 可以直接赋值给 <video src="..."> 标签进行播放
  console.log("视频 URL 已就绪:", result.videoUrl);
} else {
  console.log("提取的视频帧:", result.frames);
}

通用选项配置 (Options)

SDK 中的所有解码器都支持以下 DecodeOptions 配置：

expect ("image" | "video", 必填)

期望输出格式。使用 'video' 返回原始可播放的视频文件，使用 'image' 提取视频的关键帧。

maxFrames (Number, 选填)

当 expect='image' 时，最大提取的帧数。默认值：4。

onProgress (Function, 选填)

进度回调函数，用于在界面上展示解码进度。

返回结果 (Result)

解码成功后，将返回一个 DecoderResult 对象，包含以下内容：

type ("video" | "image")

解码后的内容类型。

videoBlob (Blob)

解码后的原始视频 Blob 数据。

videoUrl (String)

视频的本地对象 URL，可以直接用于前端视频播放器。

frames (Array of Strings, 选填)

提取的图像帧的 Blob URLs 数组（仅当 expect='image' 时存在）。

metadata (Object, 选填)

视频元数据，包含 duration（时长/秒）、width、height 以及基于 16 FPS 估算的 estimatedFrames。