103 lines
5.3 KiB
Markdown
103 lines
5.3 KiB
Markdown
# Task02：封装 WebCodecs 判定模块（utils/codecs）
|
||
|
||
## 目标
|
||
- 在 `src/utils/codecs` 封装 WebCodecs 判定逻辑
|
||
- 提供统一接口：`detectAll`、`checkAVC`、`checkHEVC`
|
||
- 返回结构包含环境、检查细节、错误与时间戳，便于 UI 展示
|
||
- 增强输出：分别判定 H.264(AVC) 与 H.265(HEVC) 的“硬解/软解”支持情况
|
||
- 可靠性校验：在 `isConfigSupported` 为真后，实际执行 `VideoDecoder.configure(config)`，若抛错或触发 `error` 回调，则视为“不支持”
|
||
|
||
## 目录结构（计划）
|
||
- `src/utils/codecs/types.ts`（类型定义）
|
||
- `src/utils/codecs/detect.ts`（具体判定逻辑）
|
||
- `src/utils/codecs/index.ts`（导出聚合）
|
||
|
||
## 类型与接口（拟定）
|
||
```ts
|
||
export type CodecStatus = 'supported' | 'unsupported' | 'unknown';
|
||
|
||
export interface CodecDetail {
|
||
hardware: CodecStatus; // 硬件解码支持
|
||
software: CodecStatus; // 软件解码支持
|
||
overall: CodecStatus; // hardware 或 software 任一为 supported 则为 supported
|
||
}
|
||
|
||
export interface CodecSupport {
|
||
webCodecs: boolean;
|
||
avc: CodecDetail;
|
||
hevc: CodecDetail;
|
||
details: {
|
||
env: {
|
||
userAgent: string;
|
||
isSecureContext: boolean;
|
||
hasVideoDecoder: boolean;
|
||
};
|
||
checks: Array<{
|
||
codec: string;
|
||
hardwareAcceleration?:
|
||
| 'require-hardware'
|
||
| 'require-software'
|
||
| 'prefer-hardware'
|
||
| 'prefer-software'
|
||
| 'no-preference';
|
||
phase: 'isConfigSupported' | 'configure';
|
||
ok: boolean;
|
||
result?: unknown; // isConfigSupported 返回或 configure 成功标记
|
||
error?: string; // 异常或 VideoDecoder error 回调信息
|
||
}>;
|
||
errors?: string[];
|
||
timestamp: number;
|
||
};
|
||
}
|
||
|
||
export async function detectAll(): Promise<CodecSupport>;
|
||
export async function checkAVCDetail(): Promise<CodecDetail>;
|
||
export async function checkHEVCDetail(): Promise<CodecDetail>;
|
||
// 可选：保留聚合态接口（返回 overall）
|
||
export async function checkAVC(): Promise<CodecStatus>;
|
||
export async function checkHEVC(): Promise<CodecStatus>;
|
||
```
|
||
|
||
## 判定逻辑（思路）
|
||
1) WebCodecs 可用性：
|
||
- `const hasVideoDecoder = typeof window.VideoDecoder !== 'undefined'`
|
||
- `const secure = isSecureContext`
|
||
- 若 `!secure || !hasVideoDecoder`：返回 `webCodecs=false`，`avc='unknown'`，`hevc='unknown'`
|
||
2) AVC 检查（代表性配置 + 硬解/软解）：
|
||
- 代表性 `codec`：`avc1.42E01E`（Baseline）、`avc1.640028`（High L4.0）
|
||
- 对每个 `codec` 分别尝试：
|
||
- `hardwareAcceleration: 'require-hardware'`（硬解）
|
||
- `hardwareAcceleration: 'require-software'`（软解）
|
||
- 先调用 `await VideoDecoder.isConfigSupported(config)`；若 `supported: true`，继续创建 `new VideoDecoder({ output, error })` 并执行 `decoder.configure(configWithDims)`：
|
||
- 为避免不完整配置导致误判，`configWithDims` 需包含最小维度：`codedWidth: 16, codedHeight: 16`，`optimizeForLatency: false`
|
||
- 若 `configure` 抛错或随后触发 `error` 回调（建议等待 ~300ms），则该路径判定为 `unsupported`
|
||
- 成功则记录为 `supported`
|
||
- 若某实现忽略 `hardwareAcceleration`（常见）：
|
||
- 回退策略：尝试 `prefer-hardware`/`prefer-software` 并记录结果为“弱证据”，UI 仍以严格 `require-*` 结果为准；弱证据仅进入 `details`
|
||
3) HEVC 检查（代表性配置 + 硬解/软解）：
|
||
- 代表性 `codec`：`hvc1`、`hev1`，以及带 profile-level 的示例：`hvc1.1.6.L93.B0`、`hev1.1.6.L93.B0`
|
||
- 检查流程同 AVC：分别对硬解/软解进行 `isConfigSupported` 与 `configure` 双重校验，维度与等待策略一致
|
||
- 注意：不同平台对 `description` 要求不一；本版默认不提供 `description`，如遇特定浏览器需补充，可在 `details` 记录并作为特例处理
|
||
4) 记录详情：
|
||
- `env`：UA、`isSecureContext`、`hasVideoDecoder`
|
||
- `checks`：每次调用的 `codec`、`hardwareAcceleration`、阶段（`isConfigSupported`/`configure`）、结果/错误
|
||
- `timestamp`：毫秒时间戳
|
||
|
||
## 错误处理与未知态
|
||
- `isConfigSupported` 可能抛错或返回不明确信息，统一捕获并记录
|
||
- 条件不足（如非安全上下文、缺少 API）时标记为 `unknown`
|
||
- 在 `isConfigSupported` 为真后仍需 `configure`：若抛错或 `error` 回调被触发（在约定时间窗内），则视为“不支持”
|
||
- 统一在完成检查后 `decoder.close()`，避免资源泄漏
|
||
|
||
## 测试计划（开发机验证）
|
||
- Chrome（Windows/macOS）：
|
||
- WebCodecs 可用；AVC 软件解码支持，硬解由平台驱动与浏览器策略决定；HEVC 通常不支持（硬/软均可能失败）
|
||
- Safari（macOS/iOS 16+）：
|
||
- WebCodecs 与 HEVC 可能支持；对 HEVC 硬解/软解的结果依平台版本而异；AVC 支持
|
||
- Firefox：
|
||
- WebCodecs 可能不可用；AVC/HEVC 显示未知
|
||
|
||
## 验收标准
|
||
- `detectAll()` 返回结构符合最新类型定义（含 `CodecDetail` 的硬解/软解与 `overall`）
|
||
- `details.checks` 对 AVC/HEVC 均包含：硬解(`require-hardware`)与软解(`require-software`)的 `isConfigSupported` 和 `configure` 两阶段记录
|
||
- 在上述浏览器场景下，页面能分别展示 H.264/H.265 的“硬解/软解/总体”状态；Safari 的 HEVC 正确反映平台支持；Chrome/Windows 的 HEVC 显示不支持或未知 |