Sentinel Video Player

Appearance

配方 · CMS / Markdown 静态嵌入 ​

参考实现:packages/embed-helper

需求:CMS、论坛、Markdown 文档、邮件里嵌视频。这些地方跑不了 npm 包, 只能贴一段 HTML。

最小可用 ​

html
<iframe
  src="https://sentinel-video.pages.dev/embed/v1.0.25/?src=https://cdn/a.m3u8&type=hls"
  allowfullscreen
  style="width:100%;aspect-ratio:16/9;border:0"
></iframe>

一个 <iframe>,没了。不需要 JS。

12 个 URL 参数 ​

参数说明
src视频地址(必填)
typehls / flv / mp4
preset目前只有 homepage-preview
live1 = 直播
lowLatency1 = 开 LL-HLS
poster封面图
autoplay muted loop播放行为
controls playsinline interactive交互行为

想自动播放就必须 muted=1

autoplay=1 单独用在绝大多数浏览器会被拒。而静态模式收不到 autoplayblocked 的补救机会(下面会讲),所以这里更要老实加 muted=1。

关键限制:这是单向的 ​

静态 iframe 没有命令通道

你只能收事件,不能发命令。

没有 Penpal 握手,发过去的命令没有回执,所以这条路根本没打通。 play() / seek() / setQuality() 这些在这个模式下都不存在。

播放行为只能在嵌入时由 URL 参数定死,之后无法改变。

需要运行时控制?换成三种 SDK 接入方式之一(React inline / React iframe / Vue iframe)。

收事件 ​

html
<iframe src="https://sentinel-video.pages.dev/embed/v1.0.25/?src=..."></iframe>
<script src="https://sentinel-video.pages.dev/embed/v1.0.25/helper.js"></script>
<script>
  SentinelEmbed.on('ended', () => { location.href = nextUrl })
  SentinelEmbed.on('error', (payload) => { console.warn(payload.code) })
</script>

helper.js 和 iframe src 同目录 —— 把 URL 末尾换成 helper.js 就行。 这样你锁了哪个版本(v4 / v4.2 / v4.2.1),helper 自动跟着,不用另记地址。

19 个契约事件一个不少全都能收到 —— 静态模式是裸广播,没有过滤逻辑。

不用 helper 也行 ​

helper.js 只是帮你做了 origin 过滤 + envelope 校验 + 事件分发。自己写也就十几行:

js
window.addEventListener('message', (ev) => {
  if (ev.origin !== 'https://sentinel-video.pages.dev') return   // 必须校验
  const msg = ev.data
  if (msg?.type !== 'event') return
  const { event, payload } = msg.payload
  if (event === 'ended') location.href = nextUrl
})

origin 校验不能省

不校验 ev.origin,页面上任何一个 iframe(包括广告)都能伪造播放事件给你。

限定 origin ​

js
const player = SentinelEmbed.createEmbedListener({
  origin: 'https://sentinel-video.pages.dev',
})
player.on('ended', () => {})

不传 origin 时不做来源过滤(只做 envelope 结构校验)。 生产环境建议显式传上,尤其是页面里有第三方 iframe 的时候。

体积 ​

helper.js gzip 约 25KB,大头是打进去的 zod(用于校验 envelope)。

<script> 场景没有模块系统可依赖,所以 protocol 和 zod 都得打进单文件。 如果这 25KB 对你的场景太重,用上面那段十几行的手写版本 —— 代价是没有 schema 校验。

使用部署方提供的地址 ​

sentinel-video.pages.dev 是默认地址。若业务环境使用另一已部署地址，由部署方提供同一精确版本目录下的 iframe 与 helper.js URL；本仓不提供自建托管操作说明。

什么时候别用这个模式 ​

你的情况建议
需要运行时控制播放用 SDK 接入(有命令通道)
需要自定义 UI / 覆盖层用 SDK 接入(静态模式改不了 iframe 内部)
需要自动播放被拒后的补救 CTA用 SDK 接入 —— 你收得到事件,但没法调 play()
只是在文章里放个视频就用这个,别上 SDK

最后一行是这个模式存在的理由:在 Markdown 里放视频不该需要一套构建工具。

相关 ​