# @cloudflare/realtimekit-virtual-background 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/

版本：0\.0\.3
npm 元数据更新时间：2026-10-19T13:11:33.842Z
中文译文更新时间：2026-11-10T03:08:09.515Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/realtimekit-virtual-background
原文对照：https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/?lang=original

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

- 包体积（解压后）：280 kB，29 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：bowser ^2\.11\.0，@cloudflare/realtimekit \>=1\.0\.1
- 首次发布：2025-05-02T14:50:22.048Z
- 最新版本发布：2026-10-19T13:11:33.629Z
- 近 30 天下载量：173468（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 2 个）

## 中文简介

[![Logo](https://docs.realtime.cloudflare.com/logo/cf.svg)](https://realtime.cloudflare.com/)

## 安装

```sh
npm install @cloudflare/realtimekit-virtual-background
```

也可以使用：`pnpm add @cloudflare/realtimekit-virtual-background`、`yarn add @cloudflare/realtimekit-virtual-background`、`bun add @cloudflare/realtimekit-virtual-background`

## README

[![Logo](https://docs.realtime.cloudflare.com/logo/cf.svg)](https://realtime.cloudflare.com/)

### 实时 Kit 视频背景变换器

在您的 RealtimeKit 会议上添加视频背景并模糊到参与者视频种子的软件包 .  
[**探索文件“**](https://docs.realtime.cloudflare.com/)  
  
[查看演示](https://demo.realtime.cloudflare.com/) • 妇女 [报告错误](https://community.cloudflare.com/c/developers/cloudflare-realtime/101) • 妇女 [请求特性](https://community.cloudflare.com/c/developers/cloudflare-realtime/101)

## 目录

-   [关于项目](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-about-the-project)
    -   [内设](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-built-with)
-   [开始](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-getting-started)
    -   [先决条件](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-prerequisites)
    -   [安装](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-installation)
-   [使用量](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-usage)
-   [捐款](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40cloudflare/realtimekit-virtual-background/#readme-license)

## 关于项目

这个软件包为在您自定义的UI执行中添加视频背景和模糊到参与者的视频反馈提供了基础.

如果你正在使用 `rtk-meeting` 组件直接并偏向抽象而不是此包,指 [UI Kit 插件](https://www.npmjs.com/package/@cloudflare/realtimekit-ui-addons)。 。 。 .

### 内设

-   [实时 Kit](https://realtime.cloudflare.com/)
-   [字体](https://typescriptlang.org/)

## 开始

### 安装

```sh
npm install @cloudflare/realtimekit-virtual-background
```

### 运行示例

1.  运行 `npm install` 在此仓库中.
2.  替换 `YOUR_AUTH_TOKEN` 内 `index.html` 带有有效的实时Kit参与者符号.
3.  运行 `npm run dev` 打开 `http://localhost:3002`。 。 。 .
4.  启用设置屏幕上的相机来尝试虚拟背景 .

## 使用量

禁用每个帧渲染视频中间软件的默认,通过让这个中间软件自行控制来提高速度和质量.

```ts
await meeting.self.setVideoMiddlewareGlobalConfig({
  disablePerFrameCanvasRendering: true
});
```

A 类 `videoBackgroundTransformer` 对象可以使用 `RealtimeKitVideoBackgroundTransformer.init({meeting: meeting})` 方法.

```ts
const videoBackgroundTransformer = await RealtimeKitVideoBackgroundTransformer.init({
  meeting,
});
```

由 : `videoBackgroundTransformer`数字 :

1.  `createStaticBackgroundVideoMiddleware` 需要一个 `imageUrl` 作为参数,然后为当前用户创建图像背景.

```ts
meeting.self.addVideoMiddleware(
    await videoBackgroundTransformer.createStaticBackgroundVideoMiddleware(imageUrl)
);
```

2.  `createBackgroundBlurVideoMiddleware` 预期 `blurStrength` (0-100)作为参数(默认为50%),并被给定的模糊Strength模糊了用户的背景.

```ts
meeting.self.addVideoMiddleware(
  await videoBackgroundTransformer.createBackgroundBlurVideoMiddleware(50)
);
```

**_说明:_** 一些浏览器或其旧版本可能不支持WebGL或本软件包使用的浏览器API. 我们建议事先检查支助情况:

```ts
if(RealtimeKitVideoBackgroundTransformer.isSupported()){
  const videoBackgroundTransformer = await RealtimeKitVideoBackgroundTransformer.init({
    meeting: meeting,
  });
  meeting.self.addVideoMiddleware(
    await videoBackgroundTransformer.createStaticBackgroundVideoMiddleware(`REPLACE_THIS_WITH_IMAGE_URL`)
  );
}
```

**_说明:_** 图像 URL 必须允许 CORS 避免覆盖画布 。 您可以在 [https://unsplash.com/ (中文(中国大陆) )](https://unsplash.com/) 打开 [https://imgur.com (中文(简体) )](https://imgur.com/)。 。 。 .

如果您想要调整分区以获得更好的、更尖锐的结果, 请在初始化 RealtimeKitVideoBackground Transfer 时通过想要的分区配置 .

```ts
const videoBackgroundTransformer = await RealtimeKitVideoBackgroundTransformer.init({
  meeting,
  segmentationConfig: {
    model: 'mlkit', // 'meet' | 'mlkit'
    backend: 'wasmSimd',
    inputResolution: '256x256', // '256x144' for meet
    pipeline: 'webgl2', // 'webgl2' | 'canvas2dCpu' // canvas2dCpu gives sharper blur, webgl2 is faster.
    targetFps: 35,
  }
});
```

## 常见问题

### 如何安装 @cloudflare/realtimekit-virtual-background？

在项目目录运行 npm install @cloudflare/realtimekit-virtual-background，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：bowser（^2\.11\.0）、@cloudflare/realtimekit（\>=1\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cloudflare/realtimekit-virtual-background 支持 TypeScript 吗？

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

### @cloudflare/realtimekit-virtual-background 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cloudflare/realtimekit-virtual-background 可以商用吗？

@cloudflare/realtimekit-virtual-background 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudflare/realtimekit-virtual-background 的下载量有多少？

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

### @cloudflare/realtimekit-virtual-background 还在维护吗？

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