# @bendyline/squisq-video-react 中文文档

规范地址：https://npmcn.com/package/%40bendyline/squisq-video-react/

版本：2\.5\.27
npm 元数据更新时间：2026-11-07T19:46:43.435Z
中文译文更新时间：2026-11-07T22:11:06.177Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bendyline/squisq-video-react
原文对照：https://npmcn.com/package/%40bendyline/squisq-video-react/?lang=original
项目主页：https://github.com/bendyline/squisq
源码仓库：https://github.com/bendyline/squisq

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.4 MB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.22\.2 \|\| ^24\.15\.0 \|\| \>=26\.0\.0
- 运行依赖：8 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-03-26T04:22:33.583Z
- 最新版本发布：2026-11-07T19:46:43.057Z
- 近 30 天下载量：6162（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：92（近 12 个月 92 个）

## 中文简介

对基于浏览器的MP4和动画-GIF导出 Squisq 文档的响应组件

## 安装

```sh
npm install @bendyline/squisq-video-react
```

也可以使用：`pnpm add @bendyline/squisq-video-react`、`yarn add @bendyline/squisq-video-react`、`bun add @bendyline/squisq-video-react`

## README

# @bendyline/squisq-视频反应

在浏览器中直接将 Squisq 文档导出到 MP4 视频或动画 GIF 的回放组件和钩子. MP4使用WebCodecs来进行硬件加速的H.264编码(带有ffmpeg.wasm工人倒计时);GIF使用该紧凑的视频作为ffmpeg的中间体. 原是全球礼仪。 html2canvas提供定型帧捕捉. MP4 携带一个 **音频** track (narration + timed media); GIF通过设计默化.

部分 [斯奎斯克语Name](https://github.com/bendyline/squisq) 单相机.

[![npm](https://img.shields.io/npm/v/@bendyline/squisq-video-react)](https://www.npmjs.com/package/@bendyline/squisq-video-react) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bendyline/squisq/blob/main/LICENSE)

## 安装

```bash
npm install @bendyline/squisq-video-react @bendyline/squisq-video @bendyline/squisq-react @bendyline/squisq
```

**同伴依赖性 :** `react` 财务报告和审定财务报表 `react-dom` (v18或v19) (中文(简体) ).

## 快速启动

### 导出按钮

```tsx
import { VideoExportButton } from '@bendyline/squisq-video-react';

function App() {
  return <VideoExportButton doc={myDoc} images={imageMap} audio={audioMap} />;
}
```

要在压缩 GIF 预设中直接打开 :

```tsx
<VideoExportButton doc={myDoc} defaultConfig={{ outputFormat: 'gif' }} />
```

GIF 动画导出到文档有标准标题的默认值 标题音轨 。 过 `captionMode: 'off'` 内 `defaultConfig` 以禁用它们,或 在导出模式中选择无。 MP4 继续默认取消标题 .

**v1.5: (中文(简体) )** `playerScript` 现在 **选项** — 浏览器导出抓取框架 从实时页面 `DocPlayer`因此,独立捆绑只需要用于 CLI/Playwright式管线. 一个新的 `defaultConfig?: Partial<VideoExportConfig>` 道具种子模式的初始质量/fps/定向/封装选择. 两个部分都接受 `colorScheme="light" | "dark"` 所以他们的入口 模式可以匹配主机应用程序; 默认保留 `light`。主机为 他们自己的主题符号可以通过 `uiPalette?: Partial<VideoExportPalette>` 改为 覆盖对话框表面、控件、状态颜色和共享主色调 用于出口行动和进度栏。 默认完成的动作是 标签 **保存 MP4/GIF 下载** 并使用浏览器下载目录. 拥有本地或文件系统访问拾取器的主机 `saveOutput` 财务报告和审定财务报表 `saveActionLabel` 提议提供 **保存为...** 换成流动.

### 完整导出 Modal

```tsx
import { VideoExportModal } from '@bendyline/squisq-video-react';

function App() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Export Video</button>
      {open && (
        <VideoExportModal
          doc={myDoc}
          images={imageMap}
          audio={audioMap}
          onClose={() => setOpen(false)}
        />
      )}
    </>
  );
}
```

## 构成部分

| 构成部分 | 说明 |
| --- | --- |
| `VideoExportModal` | 完整模式 UI — 配置 MP4/ GIF, 标题, 运动, 质量, fps, 和方向 |
| `VideoExportButton` | 通过门户打开导出模式的放入按钮 |
| `CoverImageExportModal` | 将管理过的封面保存为 PNG、 JPEG 或带边框分辨率控制的 WebP |

导入 `CoverImageExportModal` 从 `@bendyline/squisq-video-react/cover-image` 当表面只需要覆盖时 捕获。 此切入点不包括MP4/GIF编码器工人图.

## 钩子

| 钩子 | 说明 |
| --- | --- |
| `useVideoExport` | 管弦乐导出整个生命周期——抓取,编码,下载 |
| `useFrameCapture` | 挂载隐藏的 DocPlayer , 并通过 html2canvas 以 ImageBitmaps 方式抓取框架 |

## 导出选项

这个 `VideoExportModal` 让用户配置 :

-   **格式 :** MP4 视频或动画 GIF
-   **质量 :** 草稿,正常或高
-   **费斯:** 10, 15, 24, 或 30; MP4 默认为 30 fps, GIF 为 10 fps
-   **方向 :** MP4默认为1920x1080/1080x1920;GIF默认为960x540/540x960
-   **说明 :** 标准或社会
-   **动画转换( T) :** 对 MP4 默认启用,对 GIF 默认禁用

管理覆盖继承 `squisq-cover-duration` 财务报告和审定财务报表 `squisq-cover-playback` 从文档前题. `preroll` 在故事框0前添加封面 并更换音频; `overlay` 将导出期限保持不变,而 在可见的封面下面有故事和音频.

## 直接使用钩子

自定义导出 UI, 使用 `useVideoExport` 直接 :

```tsx
import { useVideoExport } from '@bendyline/squisq-video-react';

function CustomExport({ doc, images, audio }) {
  const {
    state, // 'idle' | 'preparing' | 'capturing' | 'encoding' | 'complete' | 'error'
    progress, // 0–100
    outputFormat, // 'mp4' | 'gif'
    backend, // 'webcodecs' | 'ffmpeg-wasm' | null
    elapsed,
    estimatedRemaining,
    downloadUrl,
    outputBlob, // completed Blob for host-provided save flows
    fileSize,
    audioIncluded, // whether an audio track was muxed in
    audioSkippedReason, // null when the doc had no audio; a string explains a shortfall
    error,
    startExport,
    cancel,
    reset,
  } = useVideoExport();

  return (
    <div>
      <button
        onClick={() =>
          startExport(doc, {
            outputFormat: 'gif',
            images,
            animationsEnabled: false,
          })
        }
      >
        Export GIF
      </button>
      {state === 'capturing' && <p>Progress: {progress}%</p>}
      {downloadUrl && (
        <a href={downloadUrl} download={`document.${outputFormat}`}>
          Download
        </a>
      )}
    </div>
  );
}
```

## 浏览器要求

WebCodecs H.264编码需要Chrome 94+或Edge 94+. 当WebCodecs H.264 不可用,导出会自动返回到ffmpeg。 工人们.. 要求 `SharedArrayBuffer` (即: 横穿欧林-隔离线头 (原始内容存档于2013-10-12). host page. 动画 GIF 总是执行 ffmpeg.wasm 调色板通过, 因此 还要求 `SharedArrayBuffer`包装的班级工人是安全的.

视频维度必须是 **连**: 一个奇数 `width`编号 :`height` 之前被拒绝 抓取开始而不是四舍五入(H.264's `yuv420p` 无法编码奇数 gIF导出一个H.264中间体).

### ffmpeg.wasm 运行时间资产(需要)

`@ffmpeg/core` 被固定为运行时间依赖。 主机 **必须** 发布其无害环境管理 `ffmpeg-core.js` 财务报告和审定财务报表 `ffmpeg-core.wasm` 来自同一来源的文件,并传递其 URLs (英语). 每个ffmpeg.wasm路径——编码器倒置,GIF调色板通过,以及 第二级音频混音——当 `coreURL` 缺席 :

```ts
const config = {
  ffmpegWasm: {
    // Copy from node_modules/@ffmpeg/core/dist/esm/ during your build.
    coreURL: '/ffmpeg-core/ffmpeg-core.js',
    wasmURL: '/ffmpeg-core/ffmpeg-core.wasm',
    workerURL: '/vendor/ffmpeg-core.worker.js', // for a multithread core
  },
};
```

这不仅是建议进行离线/CSP部署——这是必要的. `@ffmpeg/ffmpeg`是因为 `load()` 否则会回到硬码 `https://unpkg.com/@ffmpeg/core@<version>/…` URL, 默取和执行 未标注的第三方代码 中间出口。 Squisq拒绝触发这一倒计时;a GIF 导出无 `ffmpegWasm` 现在立即失败 而不是抓取 每个框. `packages/site/vite.config.ts` + 键 `packages/site/src/ffmpegWasmConfig.ts` 是一个完整的Vite实例(包括必须旅行的GPL通知) 与核心文件). 故意使用远程核心,将 URL 命名为 `coreURL` 当然.

使用 `supportsWebCodecs()` 在运行时进行探测 :

```ts
import {
  supportsWebCodecs,
  supportsWebCodecsH264,
  supportsWebCodecsAac,
} from '@bendyline/squisq-video-react';

if (!supportsWebCodecs()) {
  // ffmpeg.wasm fallback will be used (needs Cross-Origin-Isolation)
}
```

**音阶.** MP4 音频在可用时通过 WebCodecs AAC 粘接 (单位:千美元)`supportsWebCodecsAac()`),然后通过ffmpeg. 当跨源隔离是 可用,否则跳过 `audioIncluded: false` 加一个 `audioSkippedReason`. 音频问题从不失败导出——视频总是 完成 。 GIF 完全跳过音频准备 . `supportsWebCodecsH264(config)` 探测特定的编码器 配置; `EncoderConfig` 财务报告和审定财务报表 `FfmpegWasmLoadConfig` 也被导出.

### RNNOUSE WASM 为虚拟主机( 建议)

Media-edit denoise使用RNnoise,其包裹嵌入了3.6 MB WASM作为基座64. 一个把媒体编辑工人捆绑起来的主持人 和它的主线背面得到的 两次有效载荷。 将插件添加到页面和工人的构造中 一次,作为排放 `rnnoise-*.wasm` 首次使用时获取 :

```ts
// vite.config.ts
import { rnnoiseWasmPlugin } from '@bendyline/squisq-video-react/vite';

export default defineConfig({
  plugins: [rnnoiseWasmPlugin()],
  worker: { plugins: () => [rnnoiseWasmPlugin()] },
});
```

它采用ES和IIFE(Vite默认)工人格式,并遵循 `base` vite自己的资产 URL 的方式。 获取必须被允许 `connect-src`。 。 。 . 没有插件,一切仍然与自成一体的模块相通.

## 音频导出

`@bendyline/squisq-video-react/encoder` 并导出流媒体音频文件 自动导出音频的主机的编码器和全文件音频组合 (或保存生成的描述) :

```ts
import {
  createAudioFileEncoder,
  renderDocumentAudio,
  supportedAudioFileFormats,
} from '@bendyline/squisq-video-react/encoder';

const formats = await supportedAudioFileFormats(); // 'm4a' (AAC), 'opus-webm', 'wav' (always)
const mixed = await renderDocumentAudio(doc, { readMedia: (src) => container.readFile(src) });
if (mixed) {
  const encoder = await createAudioFileEncoder({
    format: formats[0],
    sampleRate: mixed.sampleRate,
    channels: 2,
  });
  await encoder.append([mixed.getChannelData(0), mixed.getChannelData(1)]);
  const file = await encoder.finish(); // encoder.mimeType / encoder.extension
}
```

M4A 是一种只带音频的 MP4; 以编码器拒绝的速率输入( 24 kHz TTS for AAC)被重印入流. 见 [主机指南](https://github.com/bendyline/squisq/blob/main/docs/narration-and-audio-export.md)。 。 。 .

## 完整 API 参考

见 [文件/API.md](https://github.com/bendyline/squisq/blob/main/docs/API.md) 用于完整的道具表, `VideoExportConfig`和编码器的公用事业.

## 相关软件包

| 软件包 | 说明 |
| --- | --- |
| [@bendyline/squisq-视频](https://www.npmjs.com/package/@bendyline/squisq-video) | 无头视频/GIF渲染和WASM帮助器 |
| [@bendyline/squisq (英语)](https://www.npmjs.com/package/@bendyline/squisq) | 无头核心——计划,模板,下标 |
| [@bendyline/squisq-反应](https://www.npmjs.com/package/@bendyline/squisq-react) | 渲染道克的反应组件 |
| [@bendyline/squisq-cli (英语)](https://www.npmjs.com/package/@bendyline/squisq-cli) | 用于文档转换和 MP4/GIF 渲染的 CLI |

## 许可证

此套件中的 Squisq 作者代码为 [麻省理工学院执照](https://github.com/bendyline/squisq/blob/main/LICENSE)。 。 。 .

单独分发 `@ffmpeg/core` WebAssembly 运行时间为上游 对FFmpeg和外部库的依赖. 0.12.10 软件包宣布 GPL-2.0-或-后按这些条件分发。 这个包裹船 [`NOTICE.md`](https://npmcn.com/package/%40bendyline/squisq-video-react/NOTICE.md) 报告全文 [`COPYING.GPL-2.0.txt`](https://npmcn.com/package/%40bendyline/squisq-video-react/COPYING.GPL-2.0.txt)。发布主机 `ffmpeg-core.js` 或者说 `ffmpeg-core.wasm` 材料必须随同 运行时间和保留对准确相应来源的同等访问 通知中指明的.

## 常见问题

### @bendyline/squisq-video-react 是什么？

对基于浏览器的MP4和动画-GIF导出 Squisq 文档的响应组件

### 如何安装 @bendyline/squisq-video-react？

在项目目录运行 npm install @bendyline/squisq-video-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bendyline/squisq-video-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bendyline/squisq-video-react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bendyline/squisq-video-react 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.22\.2 \|\| ^24\.15\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bendyline/squisq-video-react 可以商用吗？

@bendyline/squisq-video-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bendyline/squisq-video-react 的下载量有多少？

根据 npm 官方下载统计，@bendyline/squisq-video-react 在 2026/10/08 – 2026/11/06 这 30 天内被下载 6,162 次，日均约 205 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bendyline/squisq-video-react 还在维护吗？

最新版本 2\.5\.27 发布于 2026/11/08（今天）；至今共发布 92 个版本，其中过去 12 个月发布了 92 个；首次发布于 2026/03/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。