message KeyframeIndexEntry {
  int64  timestamp_ms   = 1;  // 关键帧 PTS，毫秒
  int64  byte_offset    = 2;  // 相对文件头的字节偏移
  int32  frame_size     = 3;  // NALU/样本大字节数
  bool   is_idr         = 4;  // 是否 IDR 帧（H.264/HEVC）
  int32  width          = 5;  // 可选：分辨率变化时用于前端重置 Canvas
  int32  height         = 6;
}

message SparseIndex {
  string video_id       = 1;
  int32  interval_sec   = 2;  // 采样间隔
  repeated KeyframeIndexEntry entries = 3;
  int64  duration_ms    = 4;
  string codec          = 5;  // "h264" | "hevc" | "vp9"
}

flowchart LR
  A[原始录制 MP4/FLV] --> B[ffprobe -show_frames -select_streams v]
  B --> C[解析 pict_type=I 及 pkt_pts/pkt_pos]
  C --> D[按 2 s 间隔采样 + 场景变化检测]
  D --> E[序列化 Protobuf]
  E --> F[上传至对象存储 & 入库]

ffprobe -v error -select_streams v:0 
  -show_entries frame=pict_type,pkt_pts_time,pkt_pos,pkt_size 
  -of csv=p=0 input.mp4 
| awk -F, '$1=="I" {print $2","$3","$4}' > keyframes.csv

# 利用 ffmpeg scene filter 产出 scene_score，阈值 0.4 以上判定为场景切换
ffmpeg -i input.mp4 -vf "select='gt(scene,0.4)',metadata=print:file=scene.txt" -f null -

sequenceDiagram
  participant U as 用户
  participant P as 播放器
  participant I as 索引服务
  participant C as CDN/对象存储
  U->>P: 拖拽进度条至 12:34
  P->>I: GET /index?video_id=xxx&t=754000
  I-->>P: {offset: 10245678, pts: 752000, is_idr: true}
  P->>C: Range: bytes=10245678-10248000
  C-->>P: 关键帧 NALU 数据
  P->>P: VideoDecoder.decode() / MSE sourceBuffer.appendBuffer()
  P-->>U: 首帧渲染 < 300 ms

async function seekTo(targetMs) {
  // 1. 命中最近关键帧
  const { offset, pts, is_idr } = await fetchIndex(videoId, targetMs);
  // 2. 请求关键帧数据（含 SPS/PPS）
  const chunk = await fetchRange(videoUrl, offset, offset + 200_000); // 200 KB 兜底
  // 3. 解码渲染
  if (window.VideoDecoder) {
    await decoder.decode(new EncodedVideoChunk({
      type: is_idr ? 'key' : 'delta',
      timestamp: pts,
      data: chunk
    }));
  } else {
    // MSE 降级：需手动拼接 initSegment + mediaSegment
    sourceBuffer.appendBuffer(concat(initSeg, chunk));
  }
}

// Delta-of-Delta 编码时间戳（假设基准间隔 2000ms）
func EncodeTimestamps(ts []int64) []byte {
    var buf bytes.Buffer
    var prev, prevDelta int64
    for i, t := range ts {
        delta := t - prev
        d2 := delta - prevDelta
        // ZigZag 映射负数
        z := (d2 << 1) ^ (d2 >> 63)
        binary.Write(&buf, binary.LittleEndian, uint64(z))
        prev, prevDelta = t, delta
    }
    return buf.Bytes()
}

// Gorilla XOR 编码字节偏移
func EncodeOffsets(off []int64) []byte {
    var buf bytes.Buffer
    var leading, trailing uint8 = 0xFF, 0
    var prev uint64
    for i, o := range off {
        cur := uint64(o)
        if i == 0 {
            binary.Write(&buf, binary.BigEndian, cur)
        } else {
            xor := cur ^ prev
            if xor == 0 {
                buf.WriteByte(0) // 控制位 0 表示与前值相同
            } else {
                lz := bits.LeadingZeros64(xor)
                tz := bits.TrailingZeros64(xor)
                if lz >= leading && tz >= trailing {
                    buf.WriteByte(1 << 6) // 控制位 10xxxxx
                    buf.WriteByte(byte(lz - leading))
                } else {
                    leading, trailing = uint8(lz), uint8(tz)
                    buf.WriteByte(2<<6 | leading) // 控制位 11xxxxxx
                    buf.WriteByte(trailing)
                    significant := xor >> trailing & ((1 << (64 - leading - trailing)) - 1)
                    // 写入有效位...
                }
            }
        }
        prev = cur
    }
    return buf.Bytes()
}

┌─────────────────────────────────────────────────────────────┐
│                    索引存储分层策略                          │
├──────────────┬──────────────┬──────────────┬────────────────┤
│   热层       │   温层       │   冷层       │   归档层       │
│  (最近 7 天) │  (7-90 天)   │  (90-365 天) │  (>1 年)       │
├──────────────┼──────────────┼──────────────┼────────────────┤
│ 介质         │ Redis Cluster│ SSD 云盘     │ HDD/对象存储   │ 冷归档存储     │
│ 格式         │ 纯内存 Map   │ 列式分块     │ Parquet + ZSTD │ ORC + ZSTD     │
│ 索引粒度     │ 全量 I 帧    │ 2 s 稀疏     │ 5 s 稀疏       │ 仅首帧+时长    │
│ 访问延迟     │ < 1 ms       │ < 5 ms       │ < 50 ms        │ 分钟级解冻     │
│ 成本占比     │ 15%          │ 30%          │ 40%            │ 15%            │
└──────────────┴──────────────┴──────────────┴────────────────┘

# OSS Lifecycle Rule 示例
- Prefix: "indexes/hot/"
  Transition:
    Days: 7
    StorageClass: IA          # 低频访问
- Prefix: "indexes/warm/"
  Transition:
    Days: 90
    StorageClass: Archive     # 归档
  Expiration:
    Days: 2555                # 7 年合规保留

# 公共 GOP 参数（写入转码模板，禁止覆盖）
-g 250 -keyint_min 250 -sc_threshold 0 -force_key_frames "expr:gte(t,n_forced*2)"

# 1080p
-c:v h264 -b:v 2500k -maxrate 2800k -bufsize 5000k -vf "scale=1920:1080"

# 720p
-c:v h264 -b:v 1200k -maxrate 1400k -bufsize 2400k -vf "scale=1280:720"

# 360p
-c:v h264 -b:v 500k  -maxrate 600k  -bufsize 1000k -vf "scale=640:360"

message ABRIndexEntry {
  int64  timestamp_ms   = 1;  // 统一时间轴锚点
  // 每个码率的字节偏移并列存储，避免多次查询
  map<string, int64> byte_offset_map = 2; // key: "1080p"|"720p"|"360p"
  map<string, int32> frame_size_map  = 3;
  bool   is_idr         = 4;
  // 统一 SPS/PPS 版本号，前端切码率时判断是否需重置解码器
  string sps_pps_hash   = 5; 
}

async function switchBitrate(newBitrate) {
  const entry = await fetchABRIndex(currentTime);
  const offset = entry.byte_offset_map[newBitrate];
  const hash   = entry.sps_pps_hash;
  
  if (hash !== decoderState.sps_pps_hash) {
    // SPS/PPS 变更：销毁旧解码器，重建并喂入新 initSegment
    await reinitDecoder(newBitrate, entry);
  } else {
    // 同构切换：直接追加关键帧数据，零感知
    const chunk = await fetchRange(manifest[newBitrate].url, offset, offset + entry.frame_size_map[newBitrate]);
    decoder.decode(new EncodedVideoChunk({ type: 'key', timestamp: entry.timestamp_ms, data: chunk }));
  }
}

// sw.js - 索引与关键帧双层缓存
const INDEX_CACHE = 'meeting-index-v3';
const FRAME_CACHE = 'meeting-frame-v3';
const MAX_FRAMES = 120; // 约 4 分钟 @ 2s 间隔

self.addEventListener('fetch', (event) => {
  const url = new URL(event.request.url);
  
  // 1. 索引请求：Stale-While-Revalidate
  if (url.pathname.includes('/index/')) {
    event.respondWith(staleWhileRevalidate(event.request, INDEX_CACHE));
    return;
  }
  
  // 2. 关键帧 Range 请求：Cache-First + 预取触发
  if (url.searchParams.has('prefetch')) {
    event.respondWith(cacheFirstThenPrefetch(event.request, FRAME_CACHE));
    return;
  }
  
  // 3. 普通视频流：不缓存（避免污染存储配额）
  event.respondWith(networkOnly(event.request));
});

async function cacheFirstThenPrefetch(request, cacheName) {
  const cache = await caches.open(cacheName);
  const cached = await cache.match(request);
  if (cached) return cached;
  
  const response = await fetch(request);
  if (response.ok) {
    // 仅缓存关键帧片段（Content-Range 匹配单帧大小）
    if (isKeyFrameResponse(response)) {
      await cache.put(request, response.clone());
      await evictLRU(cache, MAX_FRAMES);
    }
  }
  return response;
}

// 客户端上报示例 (OTLP JSON)
{
  "name": "meeting.seek",
  "spanKind": "CLIENT",
  "attributes": {
    "video.id": "rec_abc123",
    "video.duration_ms": 7200000,
    "seek.target_ms": 4523000,
    "seek.source": "drag",           // drag | click | chapter | keyboard
    "bitrate": "1080p",
    "index.cache_hit": true,
    "frame.cache_hit": false,
    "index.latency_ms": 12,
    "frame.ttfb_ms": 68,
    "frame.size_bytes": 18432,
    "decode.latency_ms": 24,
    "total.latency_ms": 104,
    "decoder": "webcodecs",          // webcodecs | mse
    "error.code": null
  },
  "events": [
    { "name": "index.fetch.start", "time": "..." },
    { "name": "index.fetch.end", "time": "..." },
    { "name": "frame.fetch.start", "time": "..." },
    { "name": "frame.first_byte", "time": "..." },
    { "name": "decode.start", "time": "..." },
    { "name": "decode.frame_ready", "time": "..." }
  ]
}

graph LR
  A[新增录制分片] --> B{是否首片?}
  B -- 是 --> C[全量解析 + 写入 Redis 热层]
  B -- 否 --> D[仅解析新分片关键帧]
  D --> E[Redis ZADD 增量追加]
  E --> F[定时任务: Redis -> 对象存储 Merge]
  F --> G[生成新版本 .idx.pb.zst]
  G --> H[原子替换 OSS Object Tag: version=v20240115]
  H --> I[CDN 刷新预热 /api/index/rec_xxx?version=latest]