ArtPlayer/docs/document/assets/plugin_ambilight.md.ChmjnhB2.js

import{_ as a,o as e,c as n,ak as i,j as t}from"./chunks/framework.xxfEszSJ.js";const g=JSON.parse('{"title":"视频背光","description":"","frontmatter":{},"headers":[],"relativePath":"plugin/ambilight.md","filePath":"plugin/ambilight.md","lastUpdated":1789497001000}'),l={name:"plugin/ambilight.md"};function p(h,s,r,d,k,c){return e(),n("div",null,s[0]||(s[0]=[i(`<h1 id="视频背光" tabindex="-1">视频背光 <a class="header-anchor" href="#视频背光" aria-label="Permalink to &quot;视频背光&quot;">​</a></h1><p><a href="./../en/plugin/ambilight.html">English</a></p><p>从视频画面采样颜色，在播放器周围显示模糊背光。插件使用 Canvas 读取像素，不需要额外 SDK，也不改变视频的播放或音频输出。</p><p>本页描述当前重构分支。生命周期修复及精确类型入口尚未发布；在线示例和未固定版本的 npm/CDN 包不等于当前候选。</p><h2 id="安装和示例" tabindex="-1">安装和示例 <a class="header-anchor" href="#安装和示例" aria-label="Permalink to &quot;安装和示例&quot;">​</a></h2><div class="language-sh vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">yarn</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> artplayer</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> artplayer-plugin-ambilight</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br></div></div><div class="language-js vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">js</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Artplayer </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;artplayer&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> artplayerPluginAmbilight </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;artplayer-plugin-ambilight&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br></div></div><p>使用 script 时先加载 ArtPlayer，再加载 <code>dist/artplayer-plugin-ambilight.js</code>，全局名为 <code>artplayerPluginAmbilight</code>。下面保留<a href="https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ambilight/index.js&amp;example=ambilight" target="_blank" rel="noreferrer">在线背光示例</a>的原始代码；应用需要提供自己的容器和可访问的视频。</p>`,8),t("div",{className:"run-code","data-libs":"./uncompiled/artplayer-plugin-ambilight/index.js"},"▶ Run Code",-1),i(`<div class="language-js vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">js</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// npm i artplayer-plugin-ambilight</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// import artplayerPluginAmbilight from &#39;artplayer-plugin-ambilight&#39;;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> art</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Artplayer</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  container: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;.artplayer-app&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  url: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;/assets/sample/video.mp4&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  autoSize: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  plugins: [</span></span>
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    artplayerPluginAmbilight</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      blur: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;50px&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      opacity: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">1</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      frequency: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">10</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      duration: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.3</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }),</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">})</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br><span class="line-number">5</span><br><span class="line-number">6</span><br><span class="line-number">7</span><br><span class="line-number">8</span><br><span class="line-number">9</span><br><span class="line-number">10</span><br><span class="line-number">11</span><br><span class="line-number">12</span><br><span class="line-number">13</span><br><span class="line-number">14</span><br><span class="line-number">15</span><br><span class="line-number">16</span><br></div></div><h2 id="配置" tabindex="-1">配置 <a class="header-anchor" href="#配置" aria-label="Permalink to &quot;配置&quot;">​</a></h2><table tabindex="0"><thead><tr><th>字段</th><th>类型</th><th>默认值</th><th>含义</th></tr></thead><tbody><tr><td><code>blur</code></td><td><code>string</code></td><td><code>&#39;50px&#39;</code></td><td>CSS 模糊半径</td></tr><tr><td><code>opacity</code></td><td><code>number</code></td><td><code>0.5</code></td><td>背光网格透明度；示例显式设置为 <code>1</code></td></tr><tr><td><code>frequency</code></td><td><code>number</code></td><td><code>10</code></td><td>每秒采样次数上限，建议使用正数；实际频率受播放和帧调度限制</td></tr><tr><td><code>duration</code></td><td><code>number</code></td><td><code>0.3</code></td><td>背光颜色过渡时长，单位秒</td></tr><tr><td><code>zIndex</code></td><td><code>number</code></td><td>实际固定为 <code>9</code></td><td>保留的历史参数，不改变实际层级</td></tr></tbody></table><p>插件按 3×3 网格采样颜色。它只在播放器处于播放状态且采样间隔满足条件时更新颜色；<code>frequency</code> 不是视频帧率设置。遮罩、裁剪或父容器的 <code>overflow</code> 样式也可能影响背光可见范围。</p><h2 id="start-和-stop" tabindex="-1">start 和 stop <a class="header-anchor" href="#start-和-stop" aria-label="Permalink to &quot;start 和 stop&quot;">​</a></h2><p>结果的 <code>name</code> 固定为 <code>artplayerPluginAmbilight</code>。在构造选项中安装时，插件收到播放器 <code>ready</code> 后开始调度：</p><div class="language-js vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">js</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> light</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> art.plugins.artplayerPluginAmbilight;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">light.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">stop</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();  </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Stop sampling and retain the last colors.</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">light.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">start</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(); </span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Resume sampling while the player is playing.</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br></div></div><p>两个方法都同步返回 <code>undefined</code>，不会播放或暂停视频。<code>stop()</code> 保留最后一次颜色；<code>start()</code> 不是“立即采一帧”的 Promise。重复调用不会创建多条采样循环。如果在播放器已经触发 <code>ready</code> 后才调用 <code>art.plugins.add(...)</code> 安装插件，需要自行调用返回结果的 <code>start()</code>。</p><p>插件没有 <code>update</code> 方法或独立的 <code>destroy</code> 方法。销毁播放器会停止帧调度、移除网格和插件订阅、释放采样画布。销毁后保留的 <code>start/stop</code> 不再启动工作。</p><h2 id="媒体访问和代理" tabindex="-1">媒体访问和代理 <a class="header-anchor" href="#媒体访问和代理" aria-label="Permalink to &quot;媒体访问和代理&quot;">​</a></h2><p>视频必须能被浏览器解码并允许 Canvas 读取像素。跨域视频需要正确的媒体跨域配置和服务端 CORS 响应；仅能播放不代表允许取色。像素读取失败时跳过该次更新并保留现有颜色，后续可读取的来源仍可恢复，插件不会绕过浏览器的跨域限制。</p><p>Canvas proxy 使用它实际输出的画布尺寸取样。其他代理能否提供可绘制画面需要分别验证；不要把一个桌面组合通过解释为所有浏览器或代理都支持。颜色采样也不代表物理显示器背光控制。</p><h2 id="typescript-兼容入口" tabindex="-1">TypeScript 兼容入口 <a class="header-anchor" href="#typescript-兼容入口" aria-label="Permalink to &quot;TypeScript 兼容入口&quot;">​</a></h2><p>根入口和 <code>/legacy</code> 保留已发布 1.1.0 的工厂类型：参数对象必填，字段可选。使用这些类型时传入 <code>{}</code> 选择默认值。JavaScript 运行时仍接受省略参数。</p><p>需要准确的可选调用、CommonJS <code>.default</code> 自引用或 NodeNext ESM 默认调用类型时，使用同一实现的 <code>/runtime</code>：</p><div class="language-ts vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ambilight </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;artplayer-plugin-ambilight/runtime&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> installLight</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ambilight</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> installDefaultLight</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ambilight.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">default</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ opacity: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">0.5</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span></code></pre><div class="line-numbers-wrapper" aria-hidden="true"><span class="line-number">1</span><br><span class="line-number">2</span><br><span class="line-number">3</span><br><span class="line-number">4</span><br></div></div><p>根声明可导入的类型包括 <code>Option</code>、<code>Result</code>、<code>Callable</code>、<code>Factory</code> 和 <code>RuntimeFactory</code>。1.0.0 的 <code>export =</code> 及必填配置字段与 1.1.0 不同；旧 <code>import = require</code> 代码可迁到 <code>/runtime</code>，读取可选字段时提供默认值。Node10 TypeScript 默认导入 <code>/runtime</code> 需要启用 <code>esModuleInterop</code>，不启用时可用 <code>import = require</code>。</p>`,17)]))}const E=a(l,[["render",p]]);export{g as __pageData,E as default};