graph LR
    A[MediaStreamTrack / 文件源] --> B(Insertable Streams Sender/Receiver)
    B -- RTCEncodedVideoFrame --> C{控制器 Controller}
    C -- 送入解码器 --> D[VideoDecoder]
    D -- VideoFrame (GPU/CPU) --> E[处理 Worker / WebGPU Kernel]
    E -- 处理后 VideoFrame --> F[VideoEncoder]
    F -- EncodedVideoChunk --> C
    C -- RTCEncodedVideoFrame --> B
    B --> G[远端渲染 / MediaRecorder / WebRTC Sender]

async function checkCodecSupport() {
  const decodeSupport = await VideoDecoder.isConfigSupported({
    codec: 'avc1.42001f', // H.264 Baseline Profile
    codedWidth: 1920,
    codedHeight: 1080
  });
  
  const encodeSupport = await VideoEncoder.isConfigSupported({
    codec: 'avc1.42001f',
    width: 1920,
    height: 1080,
    bitrate: 5_000_000,
    framerate: 30,
    hardwareAcceleration: 'prefer-hardware' // 关键：请求硬编
  });

  console.log('解码支持:', decodeSupport.supported, decodeSupport.config);
  console.log('编码支持:', encodeSupport.supported, encodeSupport.config);
  return decodeSupport.supported && encodeSupport.supported;
}

const pc = new RTCPeerConnection();
const sender = pc.addTransceiver('video', { direction: 'sendonly' }).sender;

// 关键：获取可插入流的转换器
const transformer = sender.createEncodedVideoFrameTransformer();
// transformer.readable: 从编码器流出的压缩帧 (发送前处理/分析)
// transformer.writable: 注入给编码器的压缩帧 (接收端解码后处理/重新编码)

const decoder = new VideoDecoder({
  output: handleDecodedFrame,
  error: (e) => console.error('解码错误:', e)
});

decoder.configure({
  codec: 'avc1.42001f', // 需与 SDP 协商一致
  codedWidth: 1280,
  codedHeight: 720,
  // 从 SDP 或首帧获取 description (AVCDecoderConfigurationRecord)
  description: new Uint8Array([...]) 
});

// 读取 Insertable Stream
const reader = transformer.readable.getReader();
async function readLoop() {
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    // value 为 RTCEncodedVideoFrame
    // 1. 可在此处直接操作压缩数据 (如加水印 SEI)
    // 2. 送入解码器
    decoder.decode(value); 
    // 注意：value 会被 decoder 消费，若需转发原帧需 clone()
  }
}
readLoop();

function handleDecodedFrame(frame) {
  // frame: VideoFrame (GPUTexture 或 CPU Buffer)
  // 核心：将帧传递给处理阶段 (需考虑背压)
  processingQueue.push(frame); 
}

// 假设 device, context 已初始化
// 输入 VideoFrame -> GPUTexture (零拷贝)
const gpuTexture = frame.getGPUTexture(); // 需 frame 为 GPU 布局

// 创建 Bind Group Layout / Pipeline (初始化一次)
const bindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0),
  entries: [
    { binding: 0, resource: gpuTexture.createView() }, // 输入
    { binding: 1, resource: outputTexture.createView() }, // 输出
    { binding: 2, resource: { buffer: uniformBuffer } } // 参数
  ]
});

// 录制命令
const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass();
pass.setPipeline(computePipeline);
pass.setBindGroup(0, bindGroup);
pass.dispatchWorkgroups(Math.ceil(width/16), Math.ceil(height/16));
pass.end();
device.queue.submit([encoder.finish()]);

// 关键：从输出 Texture 创建新 VideoFrame (零拷贝)
const processedFrame = new VideoFrame(outputTexture, {
  timestamp: frame.timestamp,
  format: 'rgba8unorm', // 需与编码器配置匹配
  colorSpace: 'srgb'
});
frame.close(); // 释放输入帧引用
return processedFrame;

const encoder = new VideoEncoder({
  output: handleEncodedChunk,
  error: (e) => console.error('编码错误:', e)
});

encoder.configure({
  codec: 'avc1.42001f',
  width: 1280,
  height: 720,
  bitrate: 4_000_000,
  framerate: 30,
  hardwareAcceleration: 'prefer-hardware',
  // 关键帧控制策略
  keyFrameInterval: 1000 // 每秒强制一帧关键帧 (单位ms)，或根据场景动态调整
});

function handleEncodedChunk(chunk, metadata) {
  // chunk: EncodedVideoChunk (包含 type, timestamp, byteLength, data)
  // metadata: { decoderConfigDescription } (首帧通常包含 SPS/PPS)
  
  // 构造 RTCEncodedVideoFrame 注入 writable
  const encodedFrame = new RTCEncodedVideoFrame({
    type: chunk.type, // 'key' | 'delta'
    timestamp: chunk.timestamp,
    data: chunk.data, // ArrayBuffer 或 ArrayBufferView
    // 可选：附加 metadata 供接收端使用
  });
  
  // 写入 Insertable Stream (需处理背压)
  writer.write(encodedFrame).catch(handleBackpressure);
}

// 处理阶段回调中调用
function encodeFrame(processedFrame) {
  // 可选：动态请求关键帧 (场景切换、丢包恢复)
  // if (needKeyFrame) encoder.encode(processedFrame, { keyFrame: true });
  // else 
  encoder.encode(processedFrame);
  processedFrame.close(); // 编码器消费帧后需关闭
}

// 简单的背压策略：编码器队列积压 > 阈值 时丢帧或降帧
encoder.encode(frame);
if (encoder.encodeQueueSize > 5) { // 经验值
  // 策略1: 丢弃当前处理帧 (降帧率)
  // 策略2: 请求关键帧重置管线
  // 策略3: 动态降低编码分辨率/码率
  console.warn('编码器积压，触发降级策略');
}

// 伪代码：MediaPipe FaceDetection
const detector = await FaceDetector.createFromOptions(...);
// VideoFrame -> GPUTexture -> GPUBuffer -> Tensor (WebGPU Backend)
// 或 VideoFrame -> ImageBitmap -> Tensor (WebGL Backend)
const results = await detector.detectForVideo(frame, frame.timestamp / 1000);
// 绘制关键点 -> 再次通过 WebGPU Render Pass 绘制到输出 Texture

// 核心状态定义
enum PipelineState {
  IDLE,           // 初始态
  NEGOTIATING,    // SDP 协商 / Codec 参数协商中
  INITIALIZING,   // Decoder/Encoder/Worker 实例化中
  RUNNING,        // 稳态运行
  DEGRADED,       // 降级运行 (如: 软编、降帧、降分辨率)
  RECOVERING,     // 错误恢复中 (flush -> reset -> requestKeyFrame)
  SHUTTING_DOWN   // 资源释放中
}

// 状态流转守卫 (伪代码)
class PipelineController {
  private state: PipelineState = PipelineState.IDLE;
  
  transition(target: PipelineState, payload?: any) {
    const validTransitions: Record<PipelineState, PipelineState[]> = {
      [PipelineState.IDLE]: [PipelineState.NEGOTIATING],
      [PipelineState.NEGOTIATING]: [PipelineState.INITIALIZING, PipelineState.IDLE],
      [PipelineState.INITIALIZING]: [PipelineState.RUNNING, PipelineState.IDLE],
      [PipelineState.RUNNING]: [PipelineState.DEGRADED, PipelineState.RECOVERING, PipelineState.SHUTTING_DOWN],
      [PipelineState.DEGRADED]: [PipelineState.RUNNING, PipelineState.RECOVERING, PipelineState.SHUTTING_DOWN],
      [PipelineState.RECOVERING]: [PipelineState.RUNNING, PipelineState.DEGRADED, PipelineState.SHUTTING_DOWN],
      [PipelineState.SHUTTING_DOWN]: [PipelineState.IDLE]
    };
    
    if (!validTransitions[this.state].includes(target)) {
      throw new Error(`非法状态流转: ${this.state} -> ${target}`);
    }
    this.onStateChange(this.state, target, payload);
    this.state = target;
  }
}

class VideoFramePool {
  #pool: VideoFrame[] = [];
  #config: VideoFrameInit; // 统一格式: RGBA, 1280x720, GPU layout
  
  constructor(config, preAllocCount = 4) { // 双缓冲/三缓冲 + 1 余量
    this.#config = config;
    for (let i = 0; i < preAllocCount; i++) {
      this.#pool.push(this.#createFrame());
    }
  }
  
  #createFrame() {
    // 优先尝试 GPUTexture (WebGPU 互操作最快)
    if (navigator.gpu) {
      const texture = device.createTexture({
        size: [this.#config.codedWidth, this.#config.codedHeight],
        format: 'rgba8unorm',
        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
      });
      return new VideoFrame(texture, this.#config);
    }
    // 兜底: CPU Buffer
    return new VideoFrame(new Uint8Array(this.#config.codedWidth * this.#config.codedHeight * 4), this.#config);
  }
  
  acquire(timestamp: number): VideoFrame {
    const frame = this.#pool.pop() || this.#createFrame();
    frame.timestamp = timestamp; // 复用对象必须重写 timestamp
    return frame;
  }
  
  release(frame: VideoFrame) {
    // 重置可变状态，放回池
    // 注意: 不要 close()！close() 会销毁底层 GPU 资源
    this.#pool.push(frame);
  }
}

class FrameScheduler {
  #decodeQueue = new Map<number, RTCEncodedVideoFrame>(); // key: timestamp
  #processQueue = new Map<number, VideoFrame>();
  #encodeQueue: VideoFrame[] = []; // 优先级队列
  
  // 解码回调
  onDecoded(frame: VideoFrame) {
    // 1. 丢弃过旧帧 (timestamp < lastEncodedTs - 200ms)
    // 2. 存入 processQueue
    this.#processQueue.set(frame.timestamp, frame);
    this.#tryScheduleProcess();
  }
  
  #tryScheduleProcess() {
    // 策略: 优先处理 "最接近当前时间" 的帧，或 "关键帧"
    // 避免处理极旧帧导致延迟累积
    const now = performance.now() * 1000; // us
    let targetTs = null;
    for (const ts of this.#processQueue.keys()) {
      if (ts <= now + 50_000) { // 50ms 容忍窗口
        if (targetTs === null || ts > targetTs) targetTs = ts; // 取最新的有效帧
      }
    }
    
    if (targetTs !== null) {
      const frame = this.#processQueue.get(targetTs);
      this.#processQueue.delete(targetTs);
      processingWorker.postMessage({ frame }, [frame]); // Transfer ownership
    }
  }
}

// video_process.wgsl
struct Uniforms {
  // 变换矩阵 (裁剪、旋转、缩放、镜像)
  transform: mat3x3f,
  // 色彩转换矩阵 (BT.601/BT.709 Limited/Full Range -> sRGB)
  colorMatrix: mat3x3f,
  colorOffset: vec3f,
  // 输入输出纹理尺寸
  srcSize: vec2f,
  dstSize: vec2f,
  // 滤镜参数 (示例: 锐化强度, LUT 强度)
  filterParams: vec4f,
};

@group(0) @binding(0) var<uniform> u: Uniforms;
// 输入: 可能是 NV12 双平面 (Y + UV) 或 RGBA 单平面
@group(0) @binding(1) var srcY: texture_2d<f32>; 
@group(0) @binding(2) var srcUV: texture_2d<f32>; 
// 输出: RGBA8Unorm Storage Texture
@group(0) @binding(3) var dst: texture_storage_2d<rgba8unorm, write>;

@compute @workgroup_size(16, 16)
fn main(@builtin(global_invocation_id) gid: vec3u) {
  let dstPos = vec2u(gid.xy);
  if (dstPos.x >= u.dstSize.x || dstPos.y >= u.dstSize.y) { return; }
  
  // 1. 目标坐标 -> 归一化坐标 -> 应用逆变换 -> 源坐标
  let dstNorm = vec2f(dstPos) / u.dstSize * 2.0 - 1.0; // NDC
  let srcNorm = (u.transform * vec3f(dstNorm, 1.0)).xy; // 逆变换已在 CPU 侧求逆
  let srcUv = (srcNorm + 1.0) * 0.5 * u.srcSize; // 像素坐标
  
  // 2. 采样 (支持 NV12 双线性插值手动实现 或 RGBA 直接采样)
  // 此处示例为 RGBA 单纹理采样 (假设 srcY 实际绑定 RGBA 纹理)
  let rgba = textureSampleLevel(srcY, sampler_linear_clamp, srcUv / u.srcSize, 0.0);
  
  // 3. 色彩空间转换 (BT.709 Limited -> sRGB)
  let rgbLinear = u.colorMatrix * (rgba.rgb - u.colorOffset);
  let rgbSrgb = vec3f(
    select(12.92 * rgbLinear.x, 1.055 * pow(rgbLinear.x, 1.0/2.4) - 0.055, rgbLinear.x > 0.0031308),
    select(12.92 * rgbLinear.y, 1.055 * pow(rgbLinear.y, 1.0/2.4) - 0.055, rgbLinear.y > 0.0031308),
    select(12.92 * rgbLinear.z, 1.055 * pow(rgbLinear.z, 1.0/2.4) - 0.055, rgbLinear.z > 0.0031308)
  );
  
  // 4. 简易锐化 (Unsharp Mask 近似)
  // 实际生产建议分离 Pass 或使用更高级算法
  let sharp = rgbSrgb + u.filterParams.x * (rgbSrgb - textureSampleLevel(srcY, sampler_linear_clamp, (srcUv + vec2f(1.0, 0.0)) / u.srcSize, 0.0).rgb);
  
  textureStore(dst, dstPos, vec4f(clamp(sharp, 0.0, 1.0), rgba.a));
}

class GpuProcessor {
  #pipelines = new Map<string, GPUComputePipeline>(); // Key: "format_transform_filter"
  #bindGroupLayout: GPUBindGroupLayout;
  #uniformBuffer: GPUBuffer;
  
  async process(inputFrame: VideoFrame, outputFrame: VideoFrame, params: ProcessParams) {
    const cacheKey = this.#getCacheKey(inputFrame.format, params);
    let pipeline = this.#pipelines.get(cacheKey);
    if (!pipeline) pipeline = await this.#createPipeline(cacheKey, inputFrame.format);
    
    // 更新 Uniform Buffer (单次 writeBuffer, 避免每帧创建 BindGroup)
    this.#updateUniforms(params, inputFrame, outputFrame);
    device.queue.writeBuffer(this.#uniformBuffer, 0, this.#uniformData);
    
    // 创建/复用 BindGroup (仅纹理视图变化时创建)
    const bindGroup = this.#getOrCreateBindGroup(inputFrame, outputFrame);
    
    const encoder = device.createCommandEncoder();
    const pass = encoder.beginComputePass();
    pass.setPipeline(pipeline);
    pass.setBindGroup(0, bindGroup);
    const wgSize = 16;
    pass.dispatchWorkgroups(
      Math.ceil(outputFrame.codedWidth / wgSize),
      Math.ceil(outputFrame.codedHeight / wgSize)
    );
    pass.end();
    device.queue.submit([encoder.finish()]);
  }
}

// 全局硬编信号量
const HARDWARE_ENCODER_SEMAPHORE = 3; // 经验值，留 1 给系统/其他 Tab
let currentHardwareEncoders = 0;

async function createEncoder(config) {
  if (config.hardwareAcceleration === 'prefer-hardware') {
    if (currentHardwareEncoders >= HARDWARE_ENCODER_SEMAPHORE) {
      console.warn('硬编槽位满，降级软编');
      config.hardwareAcceleration = 'prefer-software';
    } else {
      currentHardwareEncoders++;
    }
  }
  
  const encoder = new VideoEncoder({...});
  encoder.addEventListener('close', () => {
    if (config.hardwareAcceleration === 'prefer-hardware') currentHardwareEncoders--;
  });
  return encoder;
}

interface PipelineMetrics {
  // 端到端延迟 (采集 -> 渲染/发送)
  e2eLatencyMs: number; 
  // 各阶段耗时分布 (P50, P95, P99)
  stageLatency: {
    decodeMs: Histogram;
    processMs: Histogram; // GPU 提交到完成
    encodeMs: Histogram;
    networkQueueMs: Histogram; // Insertable Stream 背压等待
  };
  // 帧率与丢帧
  fps: { input: number; output: number; dropped: number; };
  // 编码质量
  bitrateKbps: number;
  keyFrameIntervalMs: number;
  // 资源
  gpuMemoryMB: number; // 估算
  encoderQueueSize: number;
  decoderQueueSize: number;
  // 错误
  errors: { type: 'decode'|'encode'|'transform'|'oom'; count: number; lastMessage: string; }[];
}

// 简易 ABR 策略 (每秒执行一次)
function adaptBitrate(stats) {
  const rtt = stats.get('outbound-rtp')?.roundTripTime * 1000; // ms
  const loss = stats.get('outbound-rtp')?.packetsLost / stats.get('outbound-rtp')?.packetsSent;
  const currentBitrate = encoderConfig.bitrate;
  
  let targetBitrate = currentBitrate;
  
  if (loss > 0.1 || rtt > 400) { // 弱网
    targetBitrate *= 0.85; // 乘法减小
  } else if (loss < 0.01 && rtt < 100 && encoder.encodeQueueSize < 2) { // 好网
    targetBitrate *= 1.05; // 加法增大
  }
  
  // 限幅
  targetBitrate = Math.clamp(targetBitrate, MIN_BITRATE, MAX_BITRATE);
  
  if (Math.abs(targetBitrate - currentBitrate) > currentBitrate * 0.1) {
    encoder.configure({ bitrate: targetBitrate });
    console.log(`ABR 调整: ${currentBitrate} -> ${targetBitrate} (Loss: ${loss}, RTT: ${rtt}ms)`);
  }
}

<!-- 合规的权限请求引导文案 (符合《App违法违规收集使用个人信息行为认定方法》) -->
<div class="permission-guide">
  <h3>申请摄像头权限</h3>
  <p>用于：<strong>实时视频会议/虚拟背景/AR滤镜</strong>功能。</p>
  <p>处理方式：<strong>视频流仅在本地浏览器处理，不上传服务器，不录制存储。</strong></p>
  <button id="grantBtn">授权开启</button>
  <button id="denyBtn">暂不授权</button>
</div>

[User Media Track] 
      |
      v
[Insertable Streams Sender] --(Encoded Frame)--> [VideoDecoder (H.264/VP8 HW Dec)]
      |                                                      |
      |                                                 [VideoFrame Pool (RGBA GPU Tex)]
      |                                                      |
      |                                                 [WebGPU Compute Pass 1: NV12->RGBA] (如需)
      |                                                      |
      |                                                 [WASM/WebGPU Inference: Segmentation Mask]
      |                                                      |
      |                                                 [WebGPU Render Pass: Composite (FG + BG + Feather)]
      |                                                      |
      |                                                 [VideoFrame Pool (Output RGBA)]
      |                                                      |
      v                                                      v
[Insertable Streams Sender] <--(Encoded Frame)-- [VideoEncoder (H.264 HW Enc, CBR/VBR)]
      |
      v
[WebRTC Transport / MediaRecorder]