mirror of
https://github.com/zhw2590582/ArtPlayer.git
synced 2026-10-12 15:26:16 -08:00
89 lines
4.4 KiB
Markdown
89 lines
4.4 KiB
Markdown
# 视频背光
|
||
|
||
[English](../en/plugin/ambilight.md)
|
||
|
||
从视频画面采样颜色，在播放器周围显示模糊背光。插件使用 Canvas 读取像素，不需要额外 SDK，也不改变视频的播放或音频输出。
|
||
|
||
本页描述当前重构分支。生命周期修复及精确类型入口尚未发布；在线示例和未固定版本的 npm/CDN 包不等于当前候选。
|
||
|
||
## 安装和示例
|
||
|
||
```sh
|
||
yarn add artplayer artplayer-plugin-ambilight
|
||
```
|
||
|
||
```js
|
||
import Artplayer from 'artplayer';
|
||
import artplayerPluginAmbilight from 'artplayer-plugin-ambilight';
|
||
```
|
||
|
||
使用 script 时先加载 ArtPlayer，再加载 `dist/artplayer-plugin-ambilight.js`，全局名为 `artplayerPluginAmbilight`。下面保留[在线背光示例](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ambilight/index.js&example=ambilight)的原始代码；应用需要提供自己的容器和可访问的视频。
|
||
|
||
<div className="run-code" data-libs="./uncompiled/artplayer-plugin-ambilight/index.js">▶ Run Code</div>
|
||
|
||
```js
|
||
// 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` 后开始调度：
|
||
|
||
```js
|
||
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`：
|
||
|
||
```ts
|
||
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`。
|