@open-rtn/plugin-beauty-effect

open-rtn-sdk 本地视频轨道美颜前处理插件。

本文档面向集成开发者，说明如何在业务中接入、配置、关闭和排查美颜插件。

安装

pnpm add @open-rtn/plugin-beauty-effect

浏览器兼容

美颜插件依赖浏览器媒体处理和 WebGL 能力。创建 processor 前建议先判断支持情况：

import { BeautyEffectExtension } from '@open-rtn/plugin-beauty-effect';

if (!BeautyEffectExtension.isSupported) {
  // 隐藏美颜开关，或提示用户当前浏览器不支持。
}

如果美颜运行时初始化失败，processor 会回退到 passthrough，保证视频继续输出。

快速接入

import { OpenRTC } from 'open-rtn-sdk';
import { BeautyEffectExtension } from '@open-rtn/plugin-beauty-effect';

const beautyExtension = new BeautyEffectExtension();
OpenRTC.registerExtensions([beautyExtension]);

const processor = beautyExtension.createProcessor({
  lighteningContrastLevel: 1,
  lighteningLevel: 0.6,
  smoothnessLevel: 0.5,
  sharpnessLevel: 0.3,
  rednessLevel: 0.1,
});

localVideoTrack.pipe(processor).pipe(localVideoTrack.processorDestination);
await processor.enable?.();

更新参数

processor.setOptions?.({
  lighteningContrastLevel: 1,
  lighteningLevel: 0.6,
  smoothnessLevel: 0.5,
  sharpnessLevel: 0.3,
  rednessLevel: 0.1,
});

setOptions() 会合并本次传入的字段。只改一个滑块时，可以只传对应字段。

| 参数 | 范围 | 含义 | |---|---:|---| | lighteningContrastLevel | 0 / 1 / 2 | 美白对比度级别 | | lighteningLevel | 0~1 | 美白 / 提亮强度 | | smoothnessLevel | 0~1 | 磨皮 / 平滑强度 | | sharpnessLevel | 0~1 | 锐化 / 清晰度增强 | | rednessLevel | 0~1 | 红润强度 |

推荐初始值：

| Preset | 参数 | |---|---| | Default | { lighteningContrastLevel: 1, lighteningLevel: 0.6, smoothnessLevel: 0.5, sharpnessLevel: 0.3, rednessLevel: 0.1 } | | Natural | { lighteningContrastLevel: 1, lighteningLevel: 0.28, smoothnessLevel: 0.36, sharpnessLevel: 0.16, rednessLevel: 0.08 } | | Bright | { lighteningContrastLevel: 1, lighteningLevel: 0.46, smoothnessLevel: 0.46, sharpnessLevel: 0.12, rednessLevel: 0.13 } | | Detail | { lighteningContrastLevel: 0, lighteningLevel: 0.24, smoothnessLevel: 0.28, sharpnessLevel: 0.26, rednessLevel: 0.06 } |

关闭与释放

临时关闭美颜时，可以保留 processor 链路并输出原始视频：

await processor.disable?.();

当用户彻底关闭美颜、切换处理链路或离开房间时，建议移除并释放 processor：

localVideoTrack.unpipe(processor);
await processor.release?.();

运行时状态

processor.onstats = (stats) => {
  console.info(stats.runtime, stats.averageFrameCostMs, stats.droppedFrames);
};

processor.onfallback = (reason, error) => {
  console.warn('Beauty fallback:', reason, error);
};

processor.onoverload = () => {
  // 可提示用户、降低视频分辨率、降低美颜强度或关闭美颜。
};

runtime 含义：

| Runtime | 含义 | |---|---| | worker-track | 优先路径，worker 内处理 VideoFrame 流 | | worker-webgl2 | 兼容路径，worker WebGL2 处理后回传帧 | | 2d | passthrough，只保证视频连续输出，不应用美颜 |

注意事项

• 美颜只能通过本插件控制，主 SDK 的 setBeautyEffect() 已废弃。
• 插件不使用 WASM、GPUPixel、外部模型、MediaPipe、ONNX、WebNN 或外部 mask provider。
• 当前效果基于 WebGL shader，对整帧视频做肤色、亮度、边缘和细节感知处理。
• 当前不做人脸检测、人体分割、精准祛痘或只针对人脸区域的独立美颜。
• 背景、衣服、文字和头发会通过 shader 权重尽量保护，但精度不能等同于分割 mask。

构建

pnpm --filter @open-rtn/plugin-beauty-effect run build

验证

pnpm --filter @open-rtn/plugin-beauty-effect run typecheck
pnpm --filter @open-rtn/plugin-beauty-effect run lint
pnpm --filter @open-rtn/plugin-beauty-effect run build:js
pnpm --filter @open-rtn/plugin-beauty-effect run pack:check