# PRD：WebCodecs AVC/HEVC 判定页面

## 1. 背景与目标
- 背景：不同浏览器/平台对 WebCodecs 的支持不一致，尤其 HEVC(H.265) 支持高度依赖平台与浏览器实现。开发者需要一个简单页面来判定当前环境是否支持 WebCodecs、AVC(H.264) 与 HEVC(H.265)。
- 目标：构建一个单页应用，使用 WebCodecs 相关 API（主要是 `VideoDecoder.isConfigSupported`）进行判定，给出清晰的结果与可追溯的详情。

## 2. 范围与非目标
- 范围：
  - 判定 WebCodecs 可用性
  - 判定 AVC(H.264) 解码支持
  - 判定 HEVC(H.265) 解码支持
  - 展示判定详情（环境、输入配置、返回信息、错误）
- 非目标：
  - 不进行视频解码、编码或渲染
  - 不做登录、权限、国际化、路由、多页

## 3. 用户场景与价值
- 前端/视频开发者打开页面即可得知当前环境是否能安全地依赖 WebCodecs 的 AVC/HEVC 解码能力，用于后续策略选择（如降级到 H.264、走 MSE 或 WebAssembly 等）。

## 4. 功能描述
- 首屏自动判定并展示三类状态：WebCodecs、AVC、HEVC。
- 提供“重新检测”按钮，重新执行全部判定。
- 在详情中展示：UA、安全上下文（`isSecureContext`）、每次 `isConfigSupported` 的输入/输出、错误信息。

## 5. 技术方案与实现策略
- 判定基于 WebCodecs：
  - WebCodecs 可用判定：`typeof window.VideoDecoder !== 'undefined'`
  - 统一使用 `VideoDecoder.isConfigSupported(config)` 来探测是否支持某种编码配置。
- AVC 探测建议：
  - 常见且广泛支持的配置字符串（示例）：
    - `avc1.42E01E`（Baseline）
    - `avc1.640028`（High Profile Level 4.0）
  - 逻辑：若任意代表性配置返回 `supported: true`，则判定为“支持”。若全部返回 `supported: false` 或抛错，则“未支持/未知”。
- HEVC 探测建议（平台相关）：
  - 尝试 `hvc1` 与 `hev1` 两种品牌。
  - 代表性字符串（示例）：
    - `hvc1.1.6.L93.B0`
    - `hev1.1.6.L93.B0`
  - 不同实现对 `description`（codec private data）与 profile-level 的要求可能不同。策略：从简到繁，先试纯 `codec`，再试带 profile-level（如上面的示例）。
- 安全上下文：
  - WebCodecs 在非安全上下文可能不可用；`!isSecureContext` 时直接给出提示，并将 AVC/HEVC 标记为 `unknown`。
- 错误处理：
  - 统一捕获异常与拒绝，记录在详情中，页面通过 Alert 简述。

### 判定调用示例（伪代码，仅文档说明）
```ts
await VideoDecoder.isConfigSupported({
  codec: 'hvc1.1.6.L93.B0',
  hardwareAcceleration: 'prefer-hardware',
});
```

## 6. 数据结构与接口（由 `utils/codecs` 对外暴露）
- 类型：
```ts
export type CodecStatus = 'supported' | 'unsupported' | 'unknown';

export interface CodecSupport {
  webCodecs: boolean;
  avc: CodecStatus;
  hevc: CodecStatus;
  details: {
    env: {
      userAgent: string;
      isSecureContext: boolean;
      hasVideoDecoder: boolean;
    };
    checks: Array<{
      codec: string; // 传入的 codec 字符串
      result?: any;  // isConfigSupported 的返回（裁剪）
      ok: boolean;   // 是否成功/支持
      error?: string;
    }>;
    errors?: string[];
    timestamp: number;
  };
}
```
- 接口：
```ts
export async function detectAll(): Promise<CodecSupport>;
export async function checkAVC(): Promise<CodecStatus>;
export async function checkHEVC(): Promise<CodecStatus>;
```

## 7. 验收标准
- 在支持 WebCodecs 且支持 HEVC 的浏览器（如部分 Safari/iOS/macOS）显示：
  - WebCodecs：可用
  - AVC：支持（大概率）
  - HEVC：支持
- 在支持 WebCodecs 但不支持 HEVC 的浏览器（如多数默认配置的 Chrome/Windows）：
  - WebCodecs：可用
  - AVC：支持
  - HEVC：不支持
- 在不支持 WebCodecs 的浏览器（如部分 Firefox）：
  - WebCodecs：不可用（Alert 提示）
  - AVC/HEVC：未知
- 详情区包含环境、检查输入/输出、错误信息与时间戳。

## 8. 兼容性与风险
- HEVC 支持强平台依赖，可能需要操作系统编解码器或浏览器实验开关；结果可能随版本变化。
- 字符串语法（profile-level）在不同实现中解析差异，需在详情中透明记录。
- 非安全上下文导致 WebCodecs 不可用。

## 9. 依赖与约束
- 依赖：现代浏览器、HTTPS 环境
- 技术栈：React + Tailwind + shadcn/ui + TypeScript + Vite

## 10. 发布与度量
- 发布：静态资源即可部署
- 度量：
  - 首屏交互完成时间（粗略）
  - 判定耗时（检测 Promise 完成时间）
  - 用户使用“重新检测”与“复制详情”的频次（可选）