Helios Player API
<helios-player> Web Component 允许你在任何 Web 应用中嵌入并控制 Helios 合成作品。它负责在 iframe 中加载合成作品，并建立用于控制和状态管理的桥接。
快速开始
<script type="module" src="path/to/@helios-project/player/dist/index.js"></script>
<helios-player src="composition.html" width="1280" height="720" controls autoplay input-props='{"title": "My Video"}'
</helios-player>
API 参考
HTML 属性
Attribute | Type | Description
src | string | 合成作品的 URL（必须包含 Helios 逻辑）
width | number | 显示宽度（若同时设置 height 则保持宽高比）
height | number | 显示高度
controls | boolean | 显示内置播放控制（播放、音量、字幕、导出）
controlslist | string | 以空格分隔的要隐藏的功能列表：nodownload、nofullscreen
autoplay | boolean | 准备就绪后立即开始播放
loop | boolean | 播放结束后循环
muted | boolean | 初始静音
poster | string | 播放前显示的图片 URL
preload | 'auto' | 'none' | 预加载行为（默认：'auto'）
interactive | boolean | 允许直接与 iframe 内容交互（禁用覆盖层）
input-props | JSON 字符串 | 向合成作品传递初始属性
export-mode | 'auto' | 'canvas' | 'dom' | 客户端导出策略（默认：'auto'）
export-format | 'mp4' | 'webm' | 客户端导出的输出格式（默认：'mp4'）
export-caption-mode | 'burn-in' | 'file' | 导出时字幕处理方式（默认：'burn-in'）
export-width | number | 导出视频宽度（独立于显示宽度）
export-height | number | 导出视频高度
export-bitrate | number | 导出目标码率（bits/s）
export-filename | string | 导出文件名（默认：'video'）
disablepictureinpicture | boolean | 禁用画中画按钮
canvas-selector | string | canvas 元素的 CSS 选择器（默认：'canvas'）
sandbox | string | iframe 沙箱标志（默认：'allow-scripts allow-same-origin'）
CSS 变量（主题）
你可以使用 CSS 变量自定义播放器外观：
helios-player { --helios-controls-bg: rgba(0, 0, 0, 0.8); --helios-text-color: #ffffff; --helios-accent-color: #ff0000; --helios-range-track-color: #555555; --helios-range-selected-color: rgba(255, 255, 255, 0.5); --helios-font-family: 'Helvetica', sans-serif; }
JavaScript API
该元素实现了类似 Standard Media API 的接口，便于与视频封装组件集成。
const player = document.querySelector('helios-player');
// 播放控制 player.play(); player.pause(); player.load(); player.requestPictureInPicture(); // 进入画中画模式 player.currentTime = 5.0; // 跳转到第 5 秒 player.currentFrame = 150; // 跳转到第 150 帧
// 音频控制 player.volume = 0.5; // 0.0 到 1.0 player.muted = true;
// 可写属性 console.log(player.duration); // 总时长（秒） console.log(player.paused); // 布尔值 console.log(player.playbackRate); // 速度倍数 console.log(player.fps); // 合成作品 FPS console.log(player.loop); // 循环状态 console.log(player.autoplay); // 自动播放状态
// 只读属性 console.log(player.videoWidth); // 固有宽度 console.log(player.videoHeight); // 固有高度 console.log(player.readyState); // 0-4（HAVE_NOTHING 到 HAVE_ENOUGH_DATA） console.log(player.networkState); // 0-3（EMPTY、IDLE、LOADING、NO_SOURCE） console.log(player.seeking); // 布尔值（拖动时为 true） console.log(player.played); // 已播放片段的 TimeRanges 对象 console.log(player.buffered); // 已缓冲片段的 TimeRanges 对象 console.log(player.seekable); // 可跳转片段的 TimeRanges 对象 console.log(player.error); // 失败时的 MediaError 对象
// 输入属性 player.inputProps = { title: "Updated Title" };
// 文本轨道 console.log(player.textTracks); const track = player.addTextTrack("captions", "English", "en");
// 访问当前活动提示 track.addEventListener("cuechange", () => { console.log("Active Cues:", track.activeCues); });
事件
播放器会派发标准媒体事件：
loadstart、loadedmetadata、loadeddata、canplay、canplaythrough
play、pause、ended、playing
timeupdate、seeking、seeked
volumechange
durationchange、ratechange
error
高级控制
如需对 Helios 状态进行底层访问，可使用 getController()。
const controller = player.getController();
if (controller) { const state = controller.getState();
// 动态更新 controller.setDuration(30); // 更新时长到 30s controller.setFps(60); // 更新 FPS 到 60 controller.setSize(1080, 1080); // 更新分辨率 controller.setMarkers([{ id: "m1", time: 5, label: "Intro" }]); }
诊断
按 Shift+D 切换覆盖层查看环境能力（WebCodecs、WebGL），或通过程序调用 diagnose()。
const report = await player.diagnose(); console.log("WebCodecs support:", report.webCodecs);
字幕
你可以通过添加 <track> 元素作为子元素来提供字幕。
<helios-player src="..."> <track kind="captions" src="captions.srt" default> </helios-player>
播放器会获取 SRT 文件并将其传递给 Helios 控制器。
客户端导出
播放器支持直接在浏览器中导出视频（使用 VideoEncoder）。
格式：支持 mp4（H.264/AAC）和 webm（VP9/Opus）。
音频：从 <audio> 元素捕获音频（必须启用 CORS）。
字幕：支持“烧录”字幕（export-caption-mode="burn-in"）或保存为旁挂文件（export-caption-mode="file"）。
分辨率：使用 export-width 和 export-height 独立于播放器尺寸配置导出分辨率。
用法：用户在控制栏中点击“Export”，或手动调用 clientSideExporter（内部 API）。
UI 功能
字幕：切换“CC”按钮以叠加显示当前字幕。
音量：滑块和静音切换。
速度：播放速率选择器（0.25x - 2x）。
全屏：切换全屏模式。
进度条：可视化播放范围指示。
响应式：控制栏会适应较小宽度（紧凑/迷你模式）。
常见问题
跨域（CORS）：播放器使用 iframe。如果 src 位于不同源，请确保设置 CORS 头。
音频导出：音频元素必须提供带 Access-Control-Allow-Origin 的数据，才能被导出器捕获。
源文件
组件：packages/player/src/index.ts
导出器：packages/player/src/features/exporter.ts