Sentinel Video Player

Appearance

配方 · 首页静音预览卡 ​

参考实现:examples/team-video-vue/LivePreviewCard.vue

需求:列表页 / 首页的卡片自动播一小段预览,静音,点击整张卡进详情页。

完整接线 ​

vue
<TeamVideoPlayer
  :source="source"
  preset="homepage-preview"
  autoplay
  muted
  :controls="false"
  :interactive="false"
  :show-error-toast="false"
  :show-retry-button="false"
  :show-autoplay-cta="false"
  :show-unmute-button="false"
  :show-compat-warning="false"
/>

关键就三件事:静音自动播放、关掉所有交互、关掉所有报错 UI。

为什么必须 muted ​

浏览器普遍禁止有声自动播放。不加 muted,autoplay 在绝大多数环境直接被拒, 卡片变成一张静止封面。

静音自动播放通常被允许 —— 这不是 SDK 的策略,是浏览器的。

interactive: false 是这个场景的关键 ​

vue
:interactive="false"

它让点击穿透播放器,落到外层卡片的 @click 上。

不加这个,用户点卡片会点在播放器上(触发播放/暂停),而不是进详情页 —— 这是预览卡最常见的接线错误。

vue
<div class="card" @click="handleClick">
  <TeamVideoPlayer :interactive="false" ... />
  <!-- 点击落到 .card 上,不被播放器吃掉 -->
</div>

为什么把报错 UI 全关掉 ​

vue
:show-error-toast="false"
:show-retry-button="false"
:show-autoplay-cta="false"

首页可能同时有十几张卡。一张预览拉流失败就弹一个 toast,首页会被报错刷屏, 而用户根本没打算看这个视频。

预览失败的正确行为是安静地退回封面图,不打扰用户。真正要看的时候进详情页, 那里再用完整的错误处理。

但别把错误吞了

UI 关掉不等于不知道。错误照样通过 @error 事件到达,应该继续上报埋点:

js
function handleError(payload) {
  analytics.track('preview_card_error', { code: payload.code })
  // 不弹 UI,但要有数据
}

否则首页预览的失败率你永远看不见。

preset 只有一个值 ​

vue
preset="homepage-preview"

契约里 PresetName 目前只有这一个枚举值(ADR-032 把原来的五个收敛成一个)。 它预置的就是首页预览这套组合。

传别的值会过不了 schema 校验。

直播预览的额外一步 ​

如果卡片放的是直播,源要标 live: true 并给双路:

ts
// useVideoSource.ts
export function liveStreamToSource(stream: LiveStream): MediaSource {
  return {
    sources: [
      { url: stream.flvUrl, type: 'flv' },
      { url: stream.hlsUrl, type: 'hls' },
    ],
    live: true,
    hls: { lowLatencyMode: true },
    poster: stream.coverUrl,
    metadata: { title: stream.title },
  } as MediaSource
}

SourceRouter 会按环境挑:桌面 Chrome 走 FLV(延迟低),iOS / 微信 / UC / 夸克 强制走 HLS。你不用自己判断 —— 详见怎么选视频源。

一个没做的优化 ​

参考实现没有用 IntersectionObserver 在卡片滚出视口时暂停。

如果你的首页有很多张预览卡,建议自己加 —— 十几个视频同时解码对低端机是真实负担:

js
const io = new IntersectionObserver(([entry]) => {
  if (entry.isIntersecting) ref.value?.play()
  else ref.value?.pause()
}, { threshold: 0.5 })

SDK 不替你做这件事:它看不到你的布局,也不知道你的卡片密度。

相关 ​