# Emscripten SDK
emsdk install 3.1.58
emsdk activate 3.1.58

# 基础依赖
npm i -g @webassemblyjs/wasm-opt binaryen

# 启用 SIMD 与多线程（需浏览器支持 COOP/COEP）
set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -msimd128 -matomics -pthread")
# 优化体积与速度平衡
set(CMAKE_C_FLAGS_RELEASE "-Oz -flto")
# 导出必要符号
set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -sEXPORTED_FUNCTIONS=_malloc,_free,_initDecoder,_decode,_flush,_destroy -sEXPORTED_RUNTIME_METHODS=ccall,cwrap,HEAPU8")

interface DecoderConfig {
  codec: 'av01.0.05M.08'; // AV1 Profile/Level 字符串
  hardwareAcceleration: 'prefer-hardware' | 'require-hardware' | 'no-hardware';
  outputFormat: 'rgba32' | 'nv12' | 'p010'; // 根据下游渲染管线决定
  maxFrameBufferCount: number;
}

interface HardwareDecoderAdapter {
  // 能力探测：返回是否支持指定 codec + 硬件加速
  static isConfigSupported(config: DecoderConfig): Promise<boolean>;
  
  // 初始化，返回解码器实例或抛出 NotSupportedError
  static create(config: DecoderConfig): Promise<VideoDecoder>;
  
  // 统一帧回调，输出 VideoFrame 对象
  onFrame: (frame: VideoFrame) => void;
  onError: (err: DOMException) => void;
}

async function createDecoder(config) {
  // 1. 尝试硬解
  if (config.hardwareAcceleration !== 'no-hardware') {
    const supported = await HardwareDecoderAdapter.isConfigSupported(config);
    if (supported) {
      try {
        return await HardwareDecoderAdapter.create(config);
      } catch (e) {
        console.warn('[Decoder] Hardware init failed, fallback to software', e);
      }
    }
  }
  // 2. 软解路径
  const dav1d = await Dav1dWasmModule();
  return dav1d.createDecoder(config);
}

{
  "testSuite": "AV1 Hardware Decode Compatibility",
  "cases": [
    {
      "id": "HW-DEC-001",
      "name": "Chrome 118 Windows Intel QuickSync 4K60 Main10",
      "env": { "os": "Windows 11", "browser": "Chrome 118", "gpu": "Intel UHD 770" },
      "stream": "av1_4k60_main10_10mbps.mp4",
      "expect": { "hardwareAccelerated": true, "droppedFrames": 0, "cpuUsageAvg": "< 15%" }
    }
  ]
}

// performance-monitor.js
const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry.entryType === 'measure' && entry.name.startsWith('decode-')) {
      metrics.decodeLatencyMs.push(entry.duration);
    }
  }
});
observer.observe({ entryTypes: ['measure'] });

// 通过 VideoDecoder.stats() 获取硬解确认
decoder.stats().then(stats => {
  metrics.hardwareAccelerated = stats.decoderImplementation === 'hardware';
});

# .github/workflows/compat-test.yml
jobs:
  compat-test:
    runs-on: [self-hosted, macos-arm64]  # 需物理机池
    strategy:
      matrix:
        device: [mac-m2, win-intel-arc, android-s8g2, ios-17-iphone15]
    steps:
      - uses: actions/checkout@v4
      - name: Deploy test page to staging
        run: npm run deploy:staging
      - name: Run Playwright test
        run: npx playwright test --project=${{ matrix.device }}
      - name: Upload metrics
        uses: actions/upload-artifact@v4
        with:
          name: metrics-${{ matrix.device }}
          path: test-results/metrics.json

// 简易自适应码率/分辨率切换逻辑
let currentQuality = '1080p';
const qualityLadder = ['4K', '1080p', '720p', '480p'];

function onStatsUpdate(stats) {
  if (stats.droppedFrames > 5 && currentQuality !== '480p') {
    currentQuality = qualityLadder[qualityLadder.indexOf(currentQuality) + 1];
    player.switchQuality(currentQuality);
  }
  if (stats.cpuUsage < 10 && currentQuality !== '4K') {
    // 可尝试升级画质
  }
}

// wasm_memory_policy.c
#define INITIAL_PAGES 256      // 16MB 启动基线
#define MAX_PAGES 2048         // 128MB 上限（移动端安全阈值）
#define FRAME_POOL_PAGES 512   // 32MB 专用帧池区

// 启动时一次性预留
__attribute__((constructor)) void reserve_memory() {
    memory.grow(FRAME_POOL_PAGES); // 规避解码期扩容抖动
}

graph LR
    A[主线程 UI] -->|控制指令| B(解码 Worker)
    B -->|SAB 帧指针+时间戳| C[渲染 Worker]
    C -->|WebGPU/Canvas| D[显示]
    B -->|统计信息| A

{
  "configurePresets": [
    { "name": "release-simd", "cacheVariables": { "CMAKE_C_FLAGS": "-Oz -msimd128" }},
    { "name": "release-threads", "cacheVariables": { "CMAKE_C_FLAGS": "-Oz -msimd128 -pthread -matomics", "LINK_FLAGS": "-pthread" }},
    { "name": "release-fallback", "cacheVariables": { "CMAKE_C_FLAGS": "-Oz" }}
  ]
}

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'wasm-unsafe-eval' https://cdn.example.com;  /* Wasm 实例化需 eval 或 wasm-unsafe-eval */
  worker-src 'self' blob:;                                      /* 解码 Worker */
  connect-src 'self' https://api.example.com wss://signal.example.com; /* 码流/信令 */
  media-src 'self' blob: https://cdn.example.com;               /* 视频源 */
  img-src 'self' data: blob:;                                   /* 封面/帧导出 */
  require-trusted-types-for 'script';                           /* 防 DOM XSS */
  trusted-types wasm-loader;                                    /* 仅允许白名单策略创建 Wasm */

enum Av1DecoderErrorCode {
  // 环境能力
  UNSUPPORTED_CODEC = 1001,        // 浏览器不支持 AV1
  UNSUPPORTED_HARDWARE = 1002,     // 硬件不支持指定 Profile/Level
  COOP_COEP_MISSING = 1003,        // 缺乏跨域隔离，多线程/SIMD 失效
  
  // 运行时故障
  DECODER_INIT_FAILED = 2001,      // VideoDecoder 构造失败
  FRAME_DECODE_TIMEOUT = 2002,     // 单帧解码超时 (> 2 帧间隔)
  GPU_PROCESS_CRASHED = 2003,      // GPU 进程崩溃 (Chrome 悲观模式)
  
  // 资源耗尽
  OOM_WASM_HEAP = 3001,            // Wasm 线性内存耗尽
  OOM_GPU_MEMORY = 3002,           // 显存/共享内存耗尽
  
  // 降级事件 (非错误，上报统计)
  FALLBACK_SOFTWARE = 4001,        // 硬解→软解
  FALLBACK_LOWER_QUALITY = 4002,   // 码率/分辨率降级
}

// 解码帧直接导入 GPU，零拷贝、零转换、支持 HDR 元数据透传
const gpuTexture = device.importExternalTexture({
  source: videoFrame, // VideoFrame 对象
  colorSpace: 'bt2020', // 显式指定色彩空间
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
});
// 在 WGSL 中直接采样
// @group(0) @binding(0) var t: texture_external;
// fn fs(@builtin(position) pos: vec4f) -> @location(0) vec4f { return textureLoad(t, pos.xy); }

av1-wasm-decoder/
├── .github/workflows/          # CI/CD: 构建矩阵、兼容性测试、性能基线对比
├── src/
│   ├── cpp/
│   │   ├── dav1d_wrapper.cpp   # dav1d C API 封装
│   │   ├── hw_adapter.cpp      # WebCodecs 硬解适配 (通过 wasm-bindgen 导出)
│   │   └── memory_pool.cpp     # 帧池/环形缓冲区实现
│   ├── ts/
│   │   ├── decoder.ts          # 统一入口：能力探测→硬解/软解工厂
│   │   ├── worker/
│   │   │   ├── decode.worker.ts    # 解码 Worker (OffscreenCanvas/WebCodecs)
│   │   │   └── render.worker.ts    # 渲染 Worker (WebGPU/Canvas2D)
│   │   ├── adapters/
│   │   │   ├── webcodecs.ts        # VideoDecoder 封装
│   │   │   └── webgpu.ts           # importExternalTexture 管线
│   │   └── utils/
│   │       ├── wasm-loader.ts      # 动态加载对应 SIMD/Threads 产物
│   │       └── metrics.ts          # 性能指标采集上报
│   └── wasm/
│       ├── CMakeLists.txt
│       └── presets.json
├── test/
│   ├── streams/                # 测试码流集 (CI 下载)
│   ├── e2e/                    # Playwright 兼容性用例
│   └── perf/                   # 基线性能脚本
├── docs/
│   ├── integration-guide.md    # 接入指南
│   ├── error-codes.md          # 错误码对照表
│   └── compliance.md           # 合规/隐私/安全清单
├── package.json
├── tsconfig.json
└── README.md

# 全矩阵构建
npm run build:all        # 产出: dist/{simd,threads,fallback}/av1-decoder.{js,wasm}

# 本地兼容性测试 (需物理设备池)
npm run test:compat -- --project=chrome-win,chrome-mac,safari-ios,firefox-android

# 性能基线对比 (输出 HTML 报告)
npm run bench:compare -- --baseline=v1.2.0 --current=HEAD