ArtPlayer/packages/artplayer-vitepress/docs/plugin/ambilight.md

视频背光

English

从视频画面采样颜色，在播放器周围显示模糊背光。插件使用 Canvas 读取像素，不需要额外 SDK，也不改变视频的播放或音频输出。

本页描述当前重构分支。生命周期修复及精确类型入口尚未发布；在线示例和未固定版本的 npm/CDN 包不等于当前候选。

安装和示例

yarn add artplayer artplayer-plugin-ambilight

import Artplayer from 'artplayer';
import artplayerPluginAmbilight from 'artplayer-plugin-ambilight';

使用 script 时先加载 ArtPlayer，再加载 dist/artplayer-plugin-ambilight.js，全局名为 artplayerPluginAmbilight。下面保留在线背光示例的原始代码；应用需要提供自己的容器和可访问的视频。

▶ Run Code

// npm i artplayer-plugin-ambilight
// import artplayerPluginAmbilight from 'artplayer-plugin-ambilight';

const art = new Artplayer({
  container: '.artplayer-app',
  url: '/assets/sample/video.mp4',
  autoSize: true,
  plugins: [
    artplayerPluginAmbilight({
      blur: '50px',
      opacity: 1,
      frequency: 10,
      duration: 0.3,
    }),
  ],
})

配置

字段	类型	默认值	含义
blur	string	'50px'	CSS 模糊半径
opacity	number	0.5	背光网格透明度；示例显式设置为 1
frequency	number	10	每秒采样次数上限，建议使用正数；实际频率受播放和帧调度限制
duration	number	0.3	背光颜色过渡时长，单位秒
zIndex	number	实际固定为 9	保留的历史参数，不改变实际层级

插件按 3×3 网格采样颜色。它只在播放器处于播放状态且采样间隔满足条件时更新颜色；frequency 不是视频帧率设置。遮罩、裁剪或父容器的 overflow 样式也可能影响背光可见范围。

start 和 stop

结果的 name 固定为 artplayerPluginAmbilight。在构造选项中安装时，插件收到播放器 ready 后开始调度：

const light = art.plugins.artplayerPluginAmbilight;
light.stop();  // Stop sampling and retain the last colors.
light.start(); // Resume sampling while the player is playing.

两个方法都同步返回 undefined，不会播放或暂停视频。stop() 保留最后一次颜色；start() 不是“立即采一帧”的 Promise。重复调用不会创建多条采样循环。如果在播放器已经触发 ready 后才调用 art.plugins.add(...) 安装插件，需要自行调用返回结果的 start()。

插件没有 update 方法或独立的 destroy 方法。销毁播放器会停止帧调度、移除网格和插件订阅、释放采样画布。销毁后保留的 start/stop 不再启动工作。

媒体访问和代理

视频必须能被浏览器解码并允许 Canvas 读取像素。跨域视频需要正确的媒体跨域配置和服务端 CORS 响应；仅能播放不代表允许取色。像素读取失败时跳过该次更新并保留现有颜色，后续可读取的来源仍可恢复，插件不会绕过浏览器的跨域限制。

Canvas proxy 使用它实际输出的画布尺寸取样。其他代理能否提供可绘制画面需要分别验证；不要把一个桌面组合通过解释为所有浏览器或代理都支持。颜色采样也不代表物理显示器背光控制。

TypeScript 兼容入口

根入口和 /legacy 保留已发布 1.1.0 的工厂类型：参数对象必填，字段可选。使用这些类型时传入 {} 选择默认值。JavaScript 运行时仍接受省略参数。

需要准确的可选调用、CommonJS .default 自引用或 NodeNext ESM 默认调用类型时，使用同一实现的 /runtime：

import ambilight from 'artplayer-plugin-ambilight/runtime';

const installLight = ambilight();
const installDefaultLight = ambilight.default({ opacity: 0.5 });

根声明可导入的类型包括 Option、Result、Callable、Factory 和 RuntimeFactory。1.0.0 的 export = 及必填配置字段与 1.1.0 不同；旧 import = require 代码可迁到 /runtime，读取可选字段时提供默认值。Node10 TypeScript 默认导入 /runtime 需要启用 esModuleInterop，不启用时可用 import = require。