message SparseIndex {
  // 视频元信息
  VideoMeta meta = 1;
  // 稀疏关键帧数组，按 PTS 升序
  repeated KeyFrameEntry entries = 2;
  // 分级缩略图映射：时间戳 -> {url, width, height}
  map<int64, ThumbnailSet> thumbnails = 3;
}

message VideoMeta {
  int64 duration_ms = 1;      // 总时长
  int32 width = 2;
  int32 height = 3;
  string codec = 4;           // h264/hevc/vp9
  int32 avg_gop_sec = 5;      // 平均 GOP 长度
}

message KeyFrameEntry {
  int64 pts_ms = 1;           // 显示时间戳
  int64 byte_offset = 2;      // 文件字节偏移
  int32 frame_size = 3;       // 帧大小（含 NALU 头）
  bool is_idr = 4;            // 是否为 IDR 帧（可独立解码入口）
}

message ThumbnailSet {
  string url_160 = 1;         // 160x90 进度条缩略图
  string url_320 = 2;         // 320x180 悬浮大图
}

# 第一遍：生成关键帧时间戳与字节偏移（输出 CSV）
ffprobe -select_streams v -show_frames -show_entries 
  frame=pts_time,pkt_pos,pkt_size,key_frame 
  -of csv=p=0 input.mp4 > frames.csv

# 第二遍：按固定间隔（如 5s）采样最近的 IDR 帧
python build_index.py --input frames.csv --interval 5000 --output index.pb

async function seekAndRender(targetMs: number) {
  // 1. 二分查找稀疏索引定位最近 IDR
  const entry = binarySearch(index.entries, targetMs, e => e.pts_ms);
  if (!entry?.is_idr) return showThumbnail(entry.pts_ms); // 兜底

  // 2. Range 请求仅拉取目标 GOP（约 200-500 KB）
  const chunk = await fetchRange(entry.byte_offset, entry.frame_size * 3);
  
  // 3. VideoDecoder (WebCodecs) 硬解首帧
  const decoder = new VideoDecoder({
    output: frame => { canvas.drawImage(frame); frame.close(); },
    error: e => fallbackToThumbnail()
  });
  decoder.configure({ codec: 'avc1.42001f', codedWidth: 1920, codedHeight: 1080 });
  decoder.decode(new EncodedVideoChunk({
    type: 'key', timestamp: entry.pts_ms * 1000, data: chunk
  }));
}

{
  "event": "drag_preview_perf",
  "video_id": "vc_12345",
  "phase": "L3_real_frame",
  "latency_ms": 142,
  "index_hit": true,
  "decoder": "webcodecs_hw",
  "network_type": "wifi",
  "client_version": "2.4.1"
}

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "实现会议录制文件秒级拖拽预览的关键帧稀疏索引构建技巧",
  "description": "详解如何通过稀疏关键帧索引、分级缩略图与 WebCodecs 硬解协同，将长视频拖拽预览延迟压缩至 200 ms 以内。",
  "author": { "@type": "Organization", "name": "{{公司名称}} 技术团队" },
  "datePublished": "{{发布日期 ISO8601}}",
  "dateModified": "{{最后修改日期 ISO8601}}",
  "keywords": ["会议录制", "关键帧索引", "WebCodecs", "MSE", "视频预览优化"],
  "articleSection": "音视频工程",
  "wordCount": 1620
}
</script>

# 伪代码：自适应间隔计算
def calc_adaptive_interval(duration_sec: int, scene_changes: List[int]) -> List[int]:
    """
    返回每个采样点的动态间隔(ms)
    策略：
    1. 基础间隔 = clamp(duration_sec / 2000, 2000, 10000)  # 2s~10s
    2. 场景变化点强制插入关键帧（不受间隔限制）
    3. 静态画面区段（屏幕共享/文档展示）间隔放宽至 15-30s
    """
    base = max(2000, min(10000, duration_sec * 1000 // 2000))
    intervals = []
    last_pts = 0
    for sc in scene_changes:
        # 场景变化前 1s 强制插帧
        if sc - last_pts > base:
            intervals.append(sc - 1000)
        intervals.append(sc)
        last_pts = sc
    # 补齐尾部
    while last_pts < duration_sec * 1000:
        last_pts += base
        intervals.append(last_pts)
    return intervals

// sw.js
self.addEventListener('install', e => {
  e.waitUntil(
    caches.open('video-index-v2').then(cache => 
      // 预热近 7 天访问过的视频索引
      getRecentVideoIds(7).then(ids => 
        Promise.all(ids.map(id => cache.add(`/index/${id}.pb.gz`)))
      )
    )
  );
});

// 页面主线程：读取索引统一入口
async function loadIndex(videoId) {
  const cached = await idbGet('index', videoId);
  if (cached && cached.expires > Date.now()) return cached.data;
  const res = await fetch(`/index/${videoId}.pb.gz`, {cache: 'force-cache'});
  const buf = await res.arrayBuffer();
  await idbPut('index', videoId, {data: buf, expires: Date.now() + 7*864e5});
  return buf;
}

graph LR
  A[用户拖拽] --> B{网络质量估算<br/>navigator.connection / RTT}
  B -- 4G/WiFi --> C[L1 缩略图 → L2 大图 → L3 真帧]
  B -- 3G/弱网 --> D[L1 缩略图 → L2 大图<br/>暂停 L3 真帧请求]
  B -- 离线/2G --> E[仅 L1 缩略图<br/>Toast 提示“网络受限，已显示预览图”]
  C --> F[上报 QoE 指标]
  D --> F
  E --> F

┌─────────────────────────────────────────────────────────────┐
│                    离线处理流水线 (SGX Enclave)              │
├─────────────────────────────────────────────────────────────┤
│  1. 输入：加密 MP4 (CENC) + Content Key (KMS 下发, 仅 Enclave 可见) │
│  2. Enclave 内部：                                            │
│     - 解密 → 仅解析容器层 (moov/moof) 获取关键帧偏移/大小     │
│     - **不落盘明文视频帧**，仅输出索引元数据                  │
│  3. 输出：加密索引文件 (AES-GCM, Key = Hash(Content Key))    │
└─────────────────────────────────────────────────────────────┘
                              ↓ CDN 分发
┌─────────────────────────────────────────────────────────────┐
│                      客户端播放流程                           │
├─────────────────────────────────────────────────────────────┤
│  1. 获取 License → 派生 Index Key                            │
│  2. 下载/解密索引 → 定位目标关键帧加密偏移                    │
│  3. Range 请求加密分段 → MSE + EME 标准解码流程               │
│  4. **关键优化**：预取目标 GOP 的 init segment + 1 个加密段   │
└─────────────────────────────────────────────────────────────┘

// 扩展后的 KeyFrameEntry
message KeyFrameEntry {
  int64 canonical_pts_ms = 1;   // 统一时间轴锚点 (最高码率关键帧 PTS)
  // 以下为各码率相对 canonical_pts_ms 的字节偏移差值
  map<string, int64> bitrate_byte_delta = 2; // key: "1080p"/"720p"
  map<string, int32> bitrate_frame_size = 3;
  bool is_idr = 4;
}

版本号格式：v{Schema}.{Algorithm}.{ConfigHash}
示例：v2.3.a1b2c3d
- Schema=2：Protobuf Schema 版本（破坏性变更才升级）
- Algorithm=3：采样算法迭代版本（自适应/场景感知等）
- ConfigHash：关键参数哈希（间隔基数、场景阈值、缩略图规格）

# .gitlab-ci.yml 片段
stages:
  - index_build
  - canary_verify
  - progressive_rollout

build_index:
  stage: index_build
  script:
    - docker run --gpus all index-builder:${ALGO_VERSION} 
        --input s3://raw/${VIDEO_ID} 
        --output s3://index/${VIDEO_ID}.v${VERSION}.pb.gz
    - echo "VERSION=$(cat version.txt)" >> build.env
  artifacts:
    reports:
      dotenv: build.env

canary_test:
  stage: canary_verify
  needs: [build_index]
  script:
    - python qoe_simulator.py --index-version $VERSION --sample 500
    - | 
      if [ $(jq '.p95_latency_ms' report.json) -gt 200 ]; then
        echo "❌ Canary failed: P95 > 200ms"; exit 1;
      fi

rollout_10_percent:
  stage: progressive_rollout
  needs: [canary_test]
  script:
    - aws s3 cp s3://index/${VIDEO_ID}.v${VERSION}.pb.gz 
        s3://index/${VIDEO_ID}.latest.pb.gz 
        --metadata-directive REPLACE 
        --metadata "rollout=10"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

rollout_full:
  stage: progressive_rollout
  needs: [rollout_10_percent]
  when: manual  # 观察 30 分钟无异常后人工确认全量
  script:
    - aws s3api put-object-tagging ... --tag-set Key=rollout,Value=100

Main Thread                          Worker Thread (OffscreenCanvas)
┌─────────────────────┐              ┌─────────────────────────────┐
│ 1. 用户拖拽 → targetMs           │              │
│ 2. postMessage({cmd:'seek',ts}) ──────────────▶│ 3. 二分查找索引 (IndexedDB)   │
│                            ◀──────────────│ 4. Range 请求加密片段         │
│ 5. 接收 ImageBitmap               │              │ 5. VideoDecoder 硬解首帧    │
│ 6. ctx.transferFromImageBitmap()  │              │ 6. 绘制到 OffscreenCanvas   │
│ 7. requestAnimationFrame 渲染     │              │ 7. postMessage(bitmap)      │
└─────────────────────┘              └─────────────────────────────┘

// worker.ts
const decoder = new VideoDecoder({
  output: (frame) => {
    // 创建 ImageBitmap 并转移所有权（零拷贝）
    createImageBitmap(frame).then(bitmap => {
      self.postMessage({type: 'frame', bitmap}, [bitmap]); // 关键：transferable
    });
    frame.close();
  },
  error: (e) => self.postMessage({type: 'error', msg: e.message})
});

// 复用 OffscreenCanvas 避免重复创建
const offscreen = new OffscreenCanvas(320, 180);
const ctx = offscreen.getContext('2d', {willReadFrequently: false});

// main.ts
worker.onmessage = (e) => {
  if (e.data.type === 'frame') {
    // 直接绘制，无需 createImageBitmap 再次解码
    mainCtx.drawImage(e.data.bitmap, 0, 0, previewW, previewH);
    e.data.bitmap.close(); // 及时释放
  }
};

export const VideoCapability = {
  async check() {
    const ua = navigator.userAgent;
    const isWeChat = /MicroMessenger/i.test(ua);
    const isHarmony = /HarmonyOS/i.test(ua);
    
    const webcodecs = 'VideoDecoder' in window && 
      await VideoDecoder.isConfigSupported({codec: 'avc1.42001f'});
    const mse = 'MediaSource' in window && MediaSource.isTypeSupported('video/mp4; codecs="avc1.42001f"');
    const offscreen = 'OffscreenCanvas' in window;
    
    return {
      mode: webcodecs ? 'webcodecs' : mse ? 'mse' : 'thumbnail',
      features: {webcodecs, mse, offscreen, indexedDB: 'indexedDB' in window},
      isWeChat, isHarmony
    };
  }
} as const;