# @bendyline/squisq-video 中文文档

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

版本：2\.4\.20
npm 元数据更新时间：2026-11-07T19:46:36.558Z
中文译文更新时间：2026-11-07T22:09:12.735Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：63.8 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.22\.2 \|\| ^24\.15\.0 \|\| \>=26\.0\.0
- 运行依赖：3 个
- 首次发布：2026-03-26T04:22:14.261Z
- 最新版本发布：2026-11-07T19:46:36.240Z
- 近 30 天下载量：6537（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：75（近 12 个月 75 个）

## 中文简介

跨运行时段视频和动画-GIF帮助器有基于浏览器的ffmpeg. 用于 Squisq 文档的编码

## 安装

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

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

## README

# @bendyline/squisq-视频

视频和动画-GIF渲染斯奎斯克文件的基础. 其纯正的时间线、质量、调色板和渲染-HTML助手在Node.js和浏览器中工作; `framesToMp4Wasm` 在浏览器运行时没有本地依赖性.

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

[![npm](https://img.shields.io/npm/v/@bendyline/squisq-video)](https://www.npmjs.com/package/@bendyline/squisq-video) [![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
```

## 里面的东西

| 导出 | 说明 |
| --- | --- |
| `generateRenderHtml(doc, options)` | 自成一体的 HTML 页面,带有无头框抓取的嵌入媒体 |
| `framesToMp4Wasm(frames, audio, options)` | 通过ffmpeg.wasm将 PNG 帧(+可选音频)编码为 MP4 |
| `computeAudioTimeline(doc, coverPreRoll?)` | 将一个 doc 的描述 + 定时介质平整为绝对定时的音频剪辑( 浏览器导出和 CLI 混合共享) |
| `bitrateForQuality(quality, width, height)` | 目标 H.264 比特率(`w*h*bitsPerPixel`)——WebCodecs比特率的单一真理源 |
| `ffmpegVideoQualityArgs`, (中文(简体) ), `audioBitrateArg`, (中文(简体) ), `ffmpegAudioMuxArgs` | 共享 FFmpeg 旗; 音频粘贴垫会简短地描述, 因此无法截取视频 |
| `ffmpegGifFilterGraph`, (中文(简体) ), `ffmpegGifOutputArgs`, (中文(简体) ), `ffmpegGifPalette*` 帮助者 | 共享全局盘 GIF 过滤器,包括双通调色板生成/应用 |
| `QUALITY_PRESETS`, (中文(简体) ), `ORIENTATION_DIMENSIONS`, (中文(简体) ), `resolveDimensions` | 质量/分配预设和帮助 |
| `validateVideoExportOptions(options)` | FPS 故障运行时间验证、尺寸、质量和方向 |
| `VideoExportOptions`, (中文(简体) ), `VideoQuality`, (中文(简体) ), `VideoOrientation`, (中文(简体) ), `GifDither`, (中文(简体) ), `QualityPreset`, (中文(简体) ), `EncoderResult` | 共享视频和GIF类型 |
| `fetchFile` | 再出口 `@ffmpeg/util`是因为 `fetchFile` 用于准备音频字节 |

这个软件包是共享的基础 [@bendyline/squisq-视频反应](https://www.npmjs.com/package/@bendyline/squisq-video-react) (浏览器导出UI)和 [@bendyline/squisq-cli (英语)](https://www.npmjs.com/package/@bendyline/squisq-cli) (单位:千美元)`squisq video`,将渲染的 HTML 与 Playwright 捕获和 ffmpeg 编码相配.

## 快速启动

### 生成渲染器 HTML

创建一个自成一体的 HTML 页面,在渲染模式中挂载独立的 Squisq 播放器,所有图像和音频嵌入为 Base64 数据 URI 。 无头浏览器( Playwright, Puppeteer) 获得玩家专用控件 `SquisqPlayer.getHandle(root)` 并使用它的渲染 API 步入帧并截取每个帧:

刻意进行实例扫描;生成的页面不曝光 高级 `window.seekTo` 或者说 `window.getDuration` 函数.

```ts
import { generateRenderHtml } from '@bendyline/squisq-video';
import { PLAYER_BUNDLE } from '@bendyline/squisq-react/standalone-source';

const html = generateRenderHtml(doc, {
  playerScript: PLAYER_BUNDLE, // the IIFE player bundle source string
  images, // Map<string, ArrayBuffer> — embedded as data URIs
  audio, // Map<string, ArrayBuffer> — embedded as data URIs
  width: 1920, // default 1920
  height: 1080, // default 1080
  captionStyle: 'standard', // 'standard' | 'social' — omit for no captions
});
```

### 编码框架到 MP4

```ts
import { framesToMp4Wasm } from '@bendyline/squisq-video';

const { data, duration } = await framesToMp4Wasm(
  frames, // Uint8Array[] — PNG frame bytes, in order
  audioBytes, // Uint8Array | null — optional WAV/MP3/AAC track (muxed as AAC)
  {
    fps: 30, // default 30
    quality: 'normal', // 'draft' | 'normal' | 'high' (default 'normal')
    orientation: 'landscape', // 'landscape' | 'portrait' (default 'landscape')
    // width / height override the orientation defaults (both must be EVEN)
    // REQUIRED — see "ffmpeg.wasm runtime assets" below:
    ffmpegWasm: {
      coreURL: '/vendor/ffmpeg-core.js',
      wasmURL: '/vendor/ffmpeg-core.wasm',
    },
    onProgress: (percent, phase) => console.log(`${phase}: ${percent}%`),
  },
);
// data: Uint8Array of MP4 bytes; duration: seconds (frames.length / fps)
```

编码为H.264(`libx264`, (中文(简体) ), `yuv420p`),带有可选的AAC音频;帧被缩放/加到目标维度上保存宽度比. ffmpeg.wasm 需要时 `SharedArrayBuffer`,这通常意味着为COOP/COEP头. `framesToMp4Wasm` 只使用浏览器;节点呼叫器可以使用 `framesToMp4Native` 或者说 `framesToMp4NativeBytes` 从 `@bendyline/squisq-cli/api`。 。 。 .

**尺寸必须均匀.** `validateVideoExportOptions` (称为 `resolveDimensions`故你应当依真理而加以否认 `width`编号 :`height` 而不是圆形: H.264's `yuv420p` 铬亚采样不能代表奇异的维度,默默地运送一个大小的调用者从未要求断裂-ratio-敏感管道. 该规则被统一应用于MP4和GIF,因此它不依赖于输出格式或运行时间.

### ffmpeg.wasm 运行时间资产

**`ffmpegWasm.coreURL` 每个ffmpeg都需要。 代码路径** (单位:千美元)`framesToMp4Wasm`中,加GIF转码和音频粘接 `@bendyline/squisq-video-react`) (中文(简体) ). 显示它会产生一个可操作错误 .

这是故意的. `@ffmpeg/ffmpeg`属于自己的 `load()` 回到硬码 `https://unpkg.com/@ffmpeg/core@<version>/…` URL,可以使这个库在运行时获取和执行无标注的第三方代码——离线/CSP限制主机的不透明故障和每个消费者的供应链表面. 斯奎斯克从来不会触发这种倒计时.

主机接线: 安装 `@ffmpeg/core`,以同源路径公布其资产,并点 `ffmpegWasm` 在他们.

```ts
import type { FfmpegWasmLoadConfig } from '@bendyline/squisq-video';

// Copy node_modules/@ffmpeg/core/dist/esm/ffmpeg-core.{js,wasm}
// into your app's static assets, then:
export const FFMPEG_WASM: FfmpegWasmLoadConfig = {
  coreURL: '/ffmpeg-core/ffmpeg-core.js',
  wasmURL: '/ffmpeg-core/ffmpeg-core.wasm',
};
```

`packages/site/vite.config.ts` (单位:千美元) `ffmpegCorePlugin`+) 加上 (中文(简体) ) `packages/site/src/ffmpegWasmConfig.ts` 是Vite的完整实例,包括必须随核心文件一起旅行的GPL通知。 故意接受远程核心,将 URL 作为 `coreURL` 明确——要求选择权属于您,而不是默默默认.

### 计划一个 Doc 的音频

`computeAudioTimeline(doc, coverPreRoll?)` 将医生的描述片段和定时媒体剪辑转换成一个平坦的绝对时间列表 `AudioTimelineClip`s. 它是纯的和可节点测试的,是浏览器MP4导出和CLI混合路径用于放置音频(因此两者从未漂移)的单一真理源. 叙述部分按顺序排列;定时媒体片段按其绝对位置排列;每个起始点由 `coverPreRoll` (default 0) 与无声封面预卷保持同步.

```ts
import { computeAudioTimeline } from '@bendyline/squisq-video';

const clips = computeAudioTimeline(doc, 2); // [{ src, startSec, sourceInSec, durationSec }, …]
```

## 质量预设

每个 `QualityPreset` 还携带 `bitsPerPixel` (用于WebCodecs比特率) 目标通过 `bitrateForQuality`和 `audioBitrate` (目标AAC比特/秒):

| 预设 | FFmpeg 预设 | 通用报告格式 | 位/ 像素 | AAC 比特率 | 使用大小写 |
| --- | --- | --- | --- | --- | --- |
| `draft` | 超级快 | 第28条 | 2个 | 96克/小时 | 快速预览 |
| `normal` | 介质 | 第23条 | 页:1 | 128克/小时 | 一般用途出口 |
| `high` | 缓慢 | 第 18 条 | 第8条 | 192千位点 | 最后产出 |

## 方向尺寸

| 方向 | 宽度 | 高度 |
| --- | --- | --- |
| `landscape` | 1920年 (中文(简体) ) | 1080号 |
| `portrait` | 1080号 | 1920年 (中文(简体) ) |

`resolveDimensions(options)` 应用这些默认值, 明确遵守 `width`编号 :`height` 超载.

见全 [API 参考](https://github.com/bendyline/squisq/blob/main/docs/API.md#bendylinesquisq-video) 所有类型.

## 相关软件包

| 软件包 | 说明 |
| --- | --- |
| [@bendyline/squisq (英语)](https://www.npmjs.com/package/@bendyline/squisq) | 无头核心——计划,模板,下标 |
| [@bendyline/squisq-反应](https://www.npmjs.com/package/@bendyline/squisq-react) | 反应组件 + 独立播放器捆绑 |
| [@bendyline/squisq-视频反应](https://www.npmjs.com/package/@bendyline/squisq-video-react) | 对浏览器视频导出进行回放 UI |
| [@bendyline/squisq-cli (英语)](https://www.npmjs.com/package/@bendyline/squisq-cli) | 用于文档转换和视频渲染的 CLI |

## 许可证

[麻省理工学院](https://github.com/bendyline/squisq/blob/main/LICENSE)

## 常见问题

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

跨运行时段视频和动画-GIF帮助器有基于浏览器的ffmpeg\. 用于 Squisq 文档的编码

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

在项目目录运行 npm install @bendyline/squisq-video，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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

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

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