术语表

本页摘自仓库的术语表,构建时 @include 抽取,零漂移同步。
这份表是术语的唯一事实源 —— ARCHITECTURE.md 和 USER-GUIDE.md 都指向它, 就是为了避免同一个词在两处朝不同方向漂移。

术语表

状态：CURRENT。 术语含义须与当前协议、技术架构和实现同步；历史设计动机到 docs/ARCHITECTURE.md 或 archive/ 追溯，不在这里保留过期定义。

本文件是术语的唯一事实源。 ARCHITECTURE.md 和 USER-GUIDE.md 均指向这里。
此前两份文档各自维护了一份术语表,已朝不同方向漂移(一份仍在描述被 ADR-025 否决的 Layer C 逃生舱,另一份把插件数停留在早期的「9 大」)。合并为单一来源即为消除该类漂移。

架构 / 通信

术语	含义
envelope	postMessage 传递的消息载荷结构,五个字段:`version` / `id` / `timestamp` / `type` / `payload`。`type` 是 `command` \| `event` \| `response` \| `error`,`id` 用于 request-response 关联
Penpal	iframe 通信库,基于 postMessage 提供 Promise-based RPC。只用于 React / Vue 两种可编程 iframe 组件；静态 iframe URL 没有 Penpal 连接，退化成裸 postMessage 单向广播事件
Zod	TypeScript-first 的 schema 校验库,同时提供类型推断和运行时校验
播放内核	播放能力抽象层；在本仓由 `player-core` 承担播放器生命周期、稳定性与统一命令/事件能力，不等同于具体流格式解码实现
通信内核	跨 iframe 通信层；在本仓由 `frame-core` 承担 RPC、握手、版本协商与双向校验，不承担媒体播放或解码
解码内核	承担具体流格式解码的底层实现；由选源结果在播放器构造时注册，不等同于播放内核或通信内核
握手	host 调 iframe 的 `handshake(hostVersion)` RPC,拿回 `{ iframeVersion, compatible, warnings }`。超时默认 15s(命令超时另算,10s)。`handshake` / `init` 属传输层方法,不在 protocol 的 CommandSchema 里——它们发生在播放器存在之前
In-place reload	切视频时不重建 iframe,内部热切换
降级链	加载失败时的多级 fallback UI

包与分层

术语	含义
protocol	`@sentinel-lab/video-protocol` 包,契约集中定义(命令 / 事件 / 错误码 / 配置)
player-core	`@sentinel-lab/video-player-core` 包,xgplayer 抽象层 + 11 个稳定性插件
player-ui	`@sentinel-lab/video-player-ui` 包,框架无关的覆盖层 custom elements(`<sentinel-poster>` / `-loading` / `-error` / `-pause`)
frame-core	`@sentinel-lab/video-frame-core` 包,iframe 通信内核
embed-app	独立部署到 CDN 的零框架应用,在 iframe 内加载
team-封装层	业务团队用自己 UI 库封装的组件(如 `TeamVideoPlayer`),不在 SDK monorepo(ADR-021)
Layer A/B	SDK API 的两层:业务概念 / 同名参数透传。没有 Layer C 逃生舱 —— 通用 passthrough 已被 ADR-025 否决,见 USER-GUIDE § 23
peerDep	peerDependency,由宿主项目提供而非包内打包

契约与测试

术语	含义
ADR	Architecture Decision Record,架构决策记录,见 `docs/adr/`
cross-mode-parity	5 种接入方式的契约一致性测试(硬红线)
幽灵契约	契约声明了但无任何实现的命令 / 事件。消费方调用或订阅后静默失效,不报错。见 ADR-033

媒体与流

术语	含义
MSE / MMS	Media Source Extensions / Managed Media Source，允许 JS 层将流媒体喂给 `<video>`。选源按能力判断：有 MSE 或 MMS 时使用 JS HLS 内核；iOS `<17.1` 等两者皆无的环境才回落原生 HLS
ABR	Adaptive Bitrate,自适应码率,HLS 根据网速自动切清晰度
LL-HLS	Low-Latency HLS,Apple 2019 年推出的低延迟 HLS 扩展,延迟 2-5s(ADR-024)
HTTP-FLV	基于 HTTP 长连接的 FLV 流协议,常用于低延迟直播(1-3s)
moov box	MP4 的元数据 box,记录每一帧的偏移和时间戳,浏览器必须先拿到 moov 才能播
faststart	FFmpeg 参数 `-movflags +faststart`,把 MP4 的 moov box 移到文件开头
Range 请求	HTTP 标准的分段下载机制,响应头 `Accept-Ranges: bytes`,状态码 206
签名 URL	带 token / expires / sig 参数的 URL,本 SDK 的唯一认证方案(ADR-022)

术语表 ​

术语表 ​

架构 / 通信 ​

包与分层 ​

契约与测试 ​

媒体与流 ​

相关文档 ​

术语表

术语表

架构 / 通信

包与分层

契约与测试

媒体与流

相关文档