@ezuikit/player-plugin-record

萤石码流本地录制插件

基于萤石播放器（@ezuikit/player-ezopen）的码流本地录制插件，在浏览器端把实时/回放码流录制为可下载的 MP4 文件。支持「水印录制（硬解转码）」与「原始码流录制」两种模式，并可选采集原始码流用于问题排查。

功能特性

• 播放器(ezopen)插件化接入，通过 player.use(plugin) 一行注册。
• 两种录制模式自动切换：
  • 水印录制：硬解（decodeEngine === 1）下经 WASM 编码器转码后录制，产物为 H264 + AAC，画面尺寸随视频动态调整，最大 1920x1080。
  • 原始码流录制：软解或关闭水印录制时，直接写入原始分片，不做转码。
• 录制产物为 MP4，支持自动下载或交由回调自定义处理。
• 支持加密流录制（传入 secretKey）。
• 与播放器生命周期联动：stop / pause 自动停止录制，destroy 自动销毁。
• 可选的原始码流另存能力（debugRecordRaw），用于码流分析与问题定位。
• 底层录制类 Record 可独立使用，适配自定义码流接入场景。

安装

# npm
npm install @ezuikit/player-plugin-record

# pnpm
pnpm add @ezuikit/player-plugin-record

# yarn
yarn add @ezuikit/player-plugin-record

该插件需配合萤石播放器 @ezuikit/player-ezopen 使用。

快速开始

import EZopenPlayer from "@ezuikit/player-ezopen";
import { PlayerPluginRecord } from "@ezuikit/player-plugin-record";

// 播放地址 url 和 accessToken 从萤石开放平台获取
// https://open.ys7.com/console/device.html
const player = new EZopenPlayer({
  id: "app",
  url: "ezopen player url",
  accessToken: "accessToken",
  width: 600,
  height: 400,
});

// 创建并注册录制插件
const recordPlugin = new PlayerPluginRecord();
player.use(recordPlugin);

// 开始录制
recordPlugin.startRecord("my-record");

// 停止录制（也会在播放器 stop/pause 时自动触发）
// recordPlugin.stopRecord();

// 销毁插件（也会在播放器 destroy 时自动触发）
// recordPlugin.destroy();

API

PlayerPluginRecord

录制插件主类，配合 EZopenPlayer 使用。

构造参数 PlayerPluginRecordProps

参数	类型	默认值	说明
downloadRecord	boolean	true	停止录制时是否自动下载录制文件。
staticPath	string	"."	底层转码库 libSystemTransformWASM.js 的资源路径前缀，支持绝对地址与相对地址（内部会解析为绝对地址）。
enabledWatermarkRecord	boolean	true	是否启用水印录制分支。true 时在硬解下经转码后录制（H264 + AAC，最大 1920x1080）；false 时走原始码流录制，不做转码。
debugRecordRaw	boolean	false	是否在录制过程中同步收集并下载原始码流，仅用于调试/码流分析，请勿在生产环境开启。仅在原始码流录制分支（enabledWatermarkRecord = false）下生效。

实例属性

属性	类型	说明
name	string	插件名称，固定为 ezuikit-player-plugin-record。
recording	boolean	当前是否处于录制中。

实例方法

• startRecord(fileName?, stopCallBack?, secretKey?): Promise<string>

  • fileName?: string 录制文件名，默认使用当前时间戳。
  • stopCallBack?: (url: string, file: Blob) => void 录制结束回调，返回文件地址与文件对象。
  • secretKey?: string 码流验证码（仅加密流需要）。
  • 开始录制。若正在录制或缺少码流头则直接返回。

• stopRecord(): Promise<string | void>

  • 停止录制。根据 downloadRecord 决定是否下载文件。

• destroy(): void

  • 停止录制并销毁插件内部资源。

• exec(player): void

  • 插件注册入口，由 player.use(plugin) 内部调用，一般无需手动调用。

Record

底层录制类，可脱离插件独立使用，适合自定义码流接入。

import { Record } from "@ezuikit/player-plugin-record";

const record = new Record({ downloadRecord: true });
record.startRecord(head /* 40 字节海康流头 */);
record.inputData(chunk); // 持续输入码流分片
record.stopRecord();
record.destroy();

构造参数 RecordOptions

参数	类型	默认值	说明
downloadRecord	boolean	true	是否下载录制文件。
staticPath	string	"."	底层转码库资源路径前缀，需可解析为绝对地址。

静态方法

• Record.getHKHead(type, videoCodec, audioCodec, audioSimpleRate): Uint8Array
  • 构造 40 字节海康码流头。
  • type: "flv" | "ps" | "rtp" | "ts"
  • videoCodec: "h264" | "h265"
  • audioCodec: "aac" | "g711_a" | "g711_u" | "g722"
  • audioSimpleRate: "8000" | "16000" | "32000" | "44100" | "48000"

实例方法

方法	说明
startRecord(aHead, name?, stopCallBack?, secretKey?)	开始录像。aHead 必须为海康 40 字节流头；FLV 流仅支持 AAC + 16K 音频。
inputData(buff)	往录像存储输入码流数据。
inputWatermarkData(rawData, info?)	输入水印（转码）码流数据。
stopRecord()	停止录像，并按 downloadRecord 决定是否下载。
destroy()	销毁录制对象。

录制模式说明

模式	触发条件	产物	说明
水印录制	enabledWatermarkRecord = true（默认）且播放器为硬解（decodeEngine === 1）	H264 + AAC MP4	经 WASM 编码器转码，画面尺寸随视频动态调整，最大 1920x1080。可录制带水印画面。
原始码流录制	软解，或 enabledWatermarkRecord = false	原始码流封装 MP4	直接写入原始分片，不做转码。可配合 debugRecordRaw 另存原始码流。

注意事项

• 水印录制仅在硬解下可用；软解环境会自动回退为原始码流录制。
• 开启水印录制后，录制视频编码会转为 H264、音频转为 AAC，尺寸最大 1920x1080；部分浏览器可能出现音频转码失败，或录制文件仅有音频、无法渲染画面的情况。
• debugRecordRaw 仅用于调试，会额外产生 .raw 文件下载，请勿在生产环境开启。
• staticPath 用于加载底层转码库 libSystemTransformWASM.js；当浏览器 new Blob 加载失败时，将回退到该路径加载，务必保证其可访问。
• 插件会自动监听播放器 stop / pause 停止录制、destroy 销毁，无需重复处理。