vgs_test_suites/.trae/prd.md

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 简述。

判定调用示例（伪代码，仅文档说明）

await VideoDecoder.isConfigSupported({
  codec: 'hvc1.1.6.L93.B0',
  hardwareAcceleration: 'prefer-hardware',
});

6. 数据结构与接口（由 utils/codecs 对外暴露）

• 类型：

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;
  };
}

• 接口：

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 完成时间）
  • 用户使用“重新检测”与“复制详情”的频次（可选）