时间特效的实现机制：从数据模型到解码执行

graph TB
    USER["用户操作：应用时间特效"]
    USER --> MODEL

    subgraph MODEL["数据模型层"]
        M1["将用户意图持久化到编辑工程"]
        M2["属性模式 / Effect 对象 / Wrapper"]
    end

    MODEL --> MAPPING

    subgraph MAPPING["时间映射层"]
        MA["输入：时间轴时刻 t"]
        MB["映射函数 f(t) = Tm"]
        MC["输出：源素材时刻 Tm"]
        MA --> MB --> MC
    end

    MAPPING --> DECODE

    subgraph DECODE["解码执行层"]
        D1["定位 Tm 所在 GOP"]
        D2["Seek 至关键帧并正向解码"]
        D3["输出目标帧至渲染管线"]
        D1 --> D2 --> D3
    end

    DECODE --> SCREEN["帧渲染上屏"]

graph TB
    ROOT["时间特效"]

    ROOT --> UNIFORM["均匀变速"]
    ROOT --> REVERSE["倒放"]
    ROOT --> CURVE["曲线变速"]
    ROOT --> REPEAT["重复"]
    ROOT --> FREEZE["定格"]

    UNIFORM --> FAST["快放：speed > 1.0"]
    UNIFORM --> SLOW["慢放：speed < 1.0"]
    REVERSE --> REV_DESC["时间方向反转，speed = -1.0"]
    CURVE --> CURVE_DESC["速度随时间变化，用关键帧定义"]
    REPEAT --> REPEAT_DESC["同一段循环播放 N 次"]
    FREEZE --> FREEZE_DESC["停留在某一帧持续一段时间"]

xychart-beta
    title "六种时间映射函数的曲线形状"
    x-axis "时间轴 t" 0 --> 10
    y-axis "源素材 Tm" 0 --> 20
    line [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    line [0, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20]
    line [0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5]
    line [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
    line [5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5]
    line [0, 1, 2, 0, 1, 2, 0, 1, 2, 0, 1]

flowchart LR
    T["时间轴时刻 t"]
    T --> CHECK{特效类型}

    CHECK -->|正常| F1["f(t) = t"]
    CHECK -->|快放/慢放| F2["f(t) = speed × t"]
    CHECK -->|倒放| F3["f(t) = D - t"]
    CHECK -->|曲线变速| F4["f(t) = ∫ speed(τ)dτ"]
    CHECK -->|重复| F5["f(t) = t mod period"]
    CHECK -->|定格| F6["f(t) = c"]

    F1 & F2 & F3 & F4 & F5 & F6 --> TM["源素材时刻 Tm"]

graph TB
    ROOT["时间特效数据建模"]

    ROOT --> STATIC["模型内持久化"]
    ROOT --> RUNTIME["运行时传播"]

    STATIC --> PROP["属性模式：直接在 Clip 上设置 speed 字段"]
    STATIC --> EFFECT["Effect 对象模式：附加 TimeWarp 对象到 Clip"]
    STATIC --> WRAPPER["Wrapper 模式：用新 Producer 包裹原始 Clip"]

    RUNTIME --> EVENT["Event 模式：通过运行时事件在 Pipeline 中传播"]

    PROP --> AVF["AVFoundation"]
    PROP --> FF["FFmpeg"]
    EFFECT --> OTIO["OpenTimelineIO"]
    WRAPPER --> MLT["MLT"]
    EVENT --> GST["GStreamer"]

    style STATIC fill:#e3f2fd
    style RUNTIME fill:#fce4ec

flowchart LR
    subgraph FFmpeg
        FF1["setpts=0.5*PTS"] --> FF2["纯 PTS 改写，METADATA_ONLY"]
    end

    subgraph MLT
        MLT1["timewarp\n'2.0:video.mp4'"] --> MLT2["包裹原始 producer\n下游透明"]
    end

    subgraph OTIO["OpenTimelineIO"]
        OT1["Clip.effects:\nLinearTimeWarp"] --> OT2["纯数据模型\n不负责执行"]
    end

    subgraph GStreamer
        GS1["Seek Event\nrate=-1.0"] --> GS2["全链路传播\n各 element 自行响应"]
    end

    subgraph AVFoundation
        AV1["scaleTimeRange\n(range, duration)"] --> AV2["修改 Composition\n时间区间"]
    end

flowchart TB
    subgraph Timeline["时间轴坐标"]
        TS["Slot: StartTime=3s, EndTime=8s"]
        TS --> SPEED["Speed=2.0"]
    end

    SPEED -->|"时间映射 f(t)"| Media

    subgraph Media["素材坐标"]
        MS["Segment: ClipStart=5s, ClipEnd=15s"]
        MS --> CROP["裁剪/变速参数"]
    end

    style Timeline fill:#e3f2fd
    style Media fill:#fff3e0

Tm = clip_start + (t - slot_start) × s

flowchart LR
    subgraph FastForward["2x 快放"]
        direction LR
        FF_T["时间轴帧: 0,1,2,3,4"] --> FF_M["映射到源帧: 0,2,4,6,8"]
    end

    subgraph SlowMotion["0.5x 慢放"]
        direction LR
        SM_T["时间轴帧: 0,1,2,3,4"] --> SM_M["映射到源帧: 0, 0.5, 1, 1.5, 2"]
        SM_M --> SM_Q{"小数帧处理?"}
        SM_Q -->|就近取整| SM_R["帧重复"]
        SM_Q -->|帧混合| SM_B["Alpha 混合"]
        SM_Q -->|帧插值| SM_I["光流/AI 超帧"]
    end

Tm = clip_end - (t - slot_start) × |s|

Tm = ∫₀ᵗ speed(τ) dτ

flowchart TB
    T["当前时间轴时刻 t"]
    KF["速度关键帧表"]

    T --> FIND["二分查找：定位 t 所在关键帧区间"]
    KF --> FIND
    FIND --> LERP["缓动插值：计算当前瞬时速度"]
    LERP --> INTEGRATE["数值积分：Tm += speed × Δt"]
    INTEGRATE --> TM["源素材时刻 Tm"]
    TM --> FRAME["解码并显示对应帧"]

flowchart LR
    subgraph Before["变速前：10s"]
        B1["1x / 3s"] --- B2["0.5x / 4s"] --- B3["2x / 3s"]
    end

    subgraph After["变速后：12.5s"]
        A1["1x / 3s"] --- A2["0.5x / 8s"] --- A3["2x / 1.5s"]
    end

    Before -->|"应用曲线变速"| After

flowchart TB
    subgraph OTIO["OpenTimelineIO"]
        O1["LinearTimeWarp：仅支持常数 time_scalar"]
        O2["曲线变速需通过 metadata 扩展"]
        O1 --> O2
    end

    subgraph MLT["MLT"]
        M1["time_remap link"]
        M2["关键帧属性 map_property"]
        M3["逐帧查表 t → Tm"]
        M1 --> M2 --> M3
    end

    subgraph GStreamer
        G1["Seek event rate"]
        G2["通过动态发送多次 seek 实现"]
        G1 --> G2
    end

    subgraph FFmpeg
        F1["setpts 表达式"]
        F2["复杂曲线需外部脚本预计算"]
        F1 --> F2
    end

    subgraph AVFoundation
        A1["scaleTimeRange 仅支持均匀变速"]
        A2["曲线变速需切分为多段分别调用"]
        A1 --> A2
    end

Tm = (t - slot_start) mod D

xychart-beta
    title "重复模式的时间映射曲线"
    x-axis "时间轴 t" 0 --> 12
    y-axis "源素材 Tm" 0 --> 5
    line [0, 1, 2, 3, 4, 5, 0, 1, 2, 3, 4, 5, 0]
    line [0, 1, 2, 3, 4, 5, 4, 3, 2, 1, 0, 1, 2]

stateDiagram-v2
    [*] --> 正常播放

    正常播放 --> 解码目标帧: 到达定格起始时刻
    解码目标帧 --> 缓存纹理: 解码完成
    缓存纹理 --> 复用缓存帧: 每帧请求直接返回
    复用缓存帧 --> 复用缓存帧: 仍在定格区间内
    复用缓存帧 --> 恢复解码器: 到达定格结束时刻
    恢复解码器 --> 正常播放

    note right of 缓存纹理: 解码器可挂起，零解码开销

graph LR
    I0["I₀ 关键帧"]
    B1["B₁"]
    B2["B₂"]
    P3["P₃"]
    B4["B₄"]
    B5["B₅"]
    P6["P₆"]

    I0 ==>|参考| P3
    P3 ==>|参考| P6
    I0 -.->|前向参考| B1
    P3 -.->|后向参考| B1
    I0 -.->|前向参考| B2
    P3 -.->|后向参考| B2
    P3 -.->|前向参考| B4
    P6 -.->|后向参考| B4
    P3 -.->|前向参考| B5
    P6 -.->|后向参考| B5

    style I0 fill:#4CAF50,color:#fff
    style P3 fill:#2196F3,color:#fff
    style P6 fill:#2196F3,color:#fff
    style B1 fill:#FF9800,color:#fff
    style B2 fill:#FF9800,color:#fff
    style B4 fill:#FF9800,color:#fff
    style B5 fill:#FF9800,color:#fff

graph BT
    TARGET["目标帧: B₅"]
    P3["P₃（前向参考）"]
    P6["P₆（后向参考）"]
    I0["I₀（关键帧）"]

    TARGET -->|依赖| P3
    TARGET -->|依赖| P6
    P3 -->|依赖| I0
    P6 -->|依赖| P3

    style TARGET fill:#f44336,color:#fff
    style I0 fill:#4CAF50,color:#fff
    style P3 fill:#2196F3,color:#fff
    style P6 fill:#2196F3,color:#fff

flowchart TB
    subgraph Forward["正向播放"]
        direction LR
        FW1["I₀"] --> FW2["P₃"] --> FW3["B₁"] --> FW4["B₂"] --> FW5["..."]
        FWN["平均代价：1 次解码/帧"]
    end

    subgraph Reverse["倒放（朴素方案）"]
        direction TB
        RV1["显示 P₉：解码 I₀→P₃→P₆→P₉ = 4 次"]
        RV2["显示 B₈：解码 I₀→P₃→P₆→P₉→B₈ = 5 次"]
        RV3["显示 B₇：解码 I₀→P₃→P₆→B₇ = 4 次"]
        RV4["..."]
        RVN["平均代价：≥3 次解码/帧"]
    end

    style Forward fill:#e8f5e9
    style Reverse fill:#ffebee

flowchart LR
    INPUT["输入流"] --> DECODE["全量解码"]
    DECODE --> BUFFER["内存缓冲区\n存储所有帧"]
    BUFFER -->|倒序输出| OUTPUT["输出流"]

flowchart LR
    INPUT["原始视频 30s"]

    INPUT --> S1["seg₀: 0-10s"]
    INPUT --> S2["seg₁: 10-20s"]
    INPUT --> S3["seg₂: 20-30s"]

    S1 -->|reverse| R1["rev₀: 10s→0s"]
    S2 -->|reverse| R2["rev₁: 20s→10s"]
    S3 -->|reverse| R3["rev₂: 30s→20s"]

    R3 -->|倒序拼接| OUTPUT["输出: 30s→0s"]
    R2 --> OUTPUT
    R1 --> OUTPUT

flowchart LR
    subgraph Forward["正向播放"]
        direction LR
        FS["Source\n顺序读取"] --> FD["Demuxer\n顺序分离"] --> FC["Decoder\n顺序解码"] --> FK["Sink\n顺序显示"]
    end

    subgraph Backward["倒放 rate=-1.0"]
        direction LR
        BS["Source\n反向读 chunk"] --> BD["Demuxer\n累积→找 I 帧\n发 GOP 数据"]
        BD --> BC["Decoder\n正向解码\n→ DISCONT 时倒序输出"]
        BC --> BK["Sink\n重打时间戳\n时钟同步"]
    end

    style Forward fill:#e8f5e9
    style Backward fill:#fce4ec

sequenceDiagram
    participant Src as Source
    participant Dmx as Demuxer
    participant Dec as Decoder
    participant Snk as Sink

    Note over Src,Snk: Seek Event (rate=-1.0) 从 Sink 向 Source 反向传播

    Src->>Dmx: 从末尾读取 chunk
    Src->>Dmx: 继续读取 chunk
    Note over Dmx: 发现关键帧，发送 GOP₂ 数据
    Dmx->>Dec: GOP₂ 数据 + DISCONT
    Note over Dec: 正向解码整个 GOP₂
    Note over Dec: 收到 DISCONT，倒序输出
    Dec->>Snk: 帧序列（倒序）
    Note over Snk: 重新计算时间戳，上屏

    Src->>Dmx: 继续反向读取 chunk
    Note over Dmx: 发现关键帧，发送 GOP₁ 数据
    Dmx->>Dec: GOP₁ 数据 + DISCONT
    Note over Dec: 正向解码，倒序输出
    Dec->>Snk: 帧序列（倒序）

flowchart LR
    READER["AVAssetReader\n逐帧读取\nSampleBuffer"] -->|分批次| BUFFER["内存缓冲\n每批次倒序\n重分配 PTS"]
    BUFFER --> WRITER["AVAssetWriter\n逐帧写入新文件"]

flowchart TB
    INPUT["源视频 456 帧"]

    INPUT --> P5["Pass 5: 帧 400-455"]
    INPUT --> P4["Pass 4: 帧 300-399"]
    INPUT --> P3["Pass 3: 帧 200-299"]
    INPUT --> P2["Pass 2: 帧 100-199"]
    INPUT --> P1["Pass 1: 帧 0-99"]

    P5 -->|倒序| R5["帧 455→400"]
    P4 -->|倒序| R4["帧 399→300"]
    P3 -->|倒序| R3["帧 299→200"]
    P2 -->|倒序| R2["帧 199→100"]
    P1 -->|倒序| R1["帧 99→0"]

    R5 -->|先写入| OUT["输出文件"]
    R4 -->|追加| OUT
    R3 -->|追加| OUT
    R2 -->|追加| OUT
    R1 -->|最后写入| OUT

    style P5 fill:#1a237e,color:#fff
    style P1 fill:#b71c1c,color:#fff

stateDiagram-v2
    [*] --> 定位末尾GOP: 开始倒放

    定位末尾GOP --> 正向解码GOP: Seek 至 I 帧
    正向解码GOP --> 缓冲解码帧: 逐帧解码
    缓冲解码帧 --> 倒序输出: GOP 解码完毕
    倒序输出 --> 倒序输出: 当前 GOP 尚有未输出帧
    倒序输出 --> 判断前续GOP: 当前 GOP 全部输出

    判断前续GOP --> 定位前一GOP: 存在更多 GOP
    定位前一GOP --> 正向解码GOP: Seek 至前一个 I 帧

    判断前续GOP --> [*]: 所有 GOP 处理完毕

    note right of 正向解码GOP: 内存峰值：单 GOP 全部解码帧
    note right of 倒序输出: 帧按显示顺序的逆序输出

quadrantChart
    title 倒放策略的设计取舍空间
    x-axis 低实现复杂度 --> 高实现复杂度
    y-axis 低实时性 --> 高实时性
    quadrant-1 理想区域
    quadrant-2 简单但离线
    quadrant-3 不推荐
    quadrant-4 复杂但值得
    A-全量缓冲-FFmpeg: [0.15, 0.15]
    B-Pipeline-GStreamer: [0.85, 0.80]
    C-预处理-AVFoundation: [0.45, 0.20]
    D-GOP级缓冲-NLE引擎: [0.55, 0.75]
    E-预索引优化: [0.70, 0.85]

flowchart LR
    subgraph GOP2["GOP₂ 倒序输出"]
        G2D["末帧"]
    end

    subgraph GOP1["GOP₁ 倒序输出"]
        G1A["首帧"]
    end

    G2D -->|"边界：可能存在视觉跳变"| G1A

    style G2D fill:#ff5722,color:#fff
    style G1A fill:#ff5722,color:#fff

flowchart TB
    PROBLEM["GOP 边界视觉跳变"]

    PROBLEM --> S1["重叠解码"]
    PROBLEM --> S2["接受跳变"]
    PROBLEM --> S3["预处理消除"]

    S1 --> S1D["相邻 GOP 多解码几帧\n边界交叉淡入淡出"]
    S2 --> S2D["不处理\n多数场景人眼不可察觉"]
    S3 --> S3D["高质量编码重新编码\n消除量化误差"]

    S1D --> R1["计算量 +20%，效果最好"]
    S2D --> R2["零代价，适用多数场景"]
    S3D --> R3["需要预处理时间"]

flowchart TB
    START{"下一帧需要显示？"}
    START -->|是| DECODE_SHOW["解码并显示"]
    START -->|否| CHECK{"该帧是否为参考帧？"}
    CHECK -->|是| DECODE_SKIP["解码但不显示"]
    CHECK -->|否| SAFE_SKIP["安全跳过解码"]
    CHECK -->|不确定| DECODE_SKIP

    DECODE_SHOW --> NEXT["处理下一帧"]
    DECODE_SKIP --> NEXT
    SAFE_SKIP --> NEXT

    style DECODE_SHOW fill:#4CAF50,color:#fff
    style DECODE_SKIP fill:#FF9800,color:#fff
    style SAFE_SKIP fill:#9E9E9E,color:#fff

flowchart LR
    subgraph A["帧重复"]
        A1["源帧 N"] --> A2["显示 N, N"]
    end

    subgraph B["帧混合"]
        B1["源帧 N"] --> B3["Alpha Blend"]
        B2["源帧 N+1"] --> B3
    end

    subgraph C["帧插值"]
        C1["源帧 N"] --> C3["光流估计 / AI 超帧"]
        C2["源帧 N+1"] --> C3
    end

    style A fill:#fff3e0
    style B fill:#e3f2fd
    style C fill:#e8f5e9

flowchart LR
    subgraph VideoPath["视频变速"]
        V["视频帧流"] --> VP["PTS 改写或帧选择"]
    end

    subgraph AudioPath["音频变速"]
        A["音频采样流"] --> AQ{"保持音高？"}
        AQ -->|否| AT["直接重采样"]
        AQ -->|是| AW["时域拉伸\nWSOLA / Phase Vocoder"]
    end

    VP --> SYNC["音视频 PTS 对齐"]
    AudioPath --> SYNC
    SYNC --> OUT["同步输出"]

block-beta
    columns 5

    block:ffmpeg:1
        columns 1
        ff_title["FFmpeg"]
        ff1["demux"]
        ff2["decode"]
        ff3["setpts filter"]
        ff4["encode"]
        ff5["mux"]
    end

    block:mlt:1
        columns 1
        mlt_title["MLT"]
        mlt1["timewarp producer"]
        mlt2["filter chain"]
        mlt3["consumer"]
        space
        space
    end

    block:otio:1
        columns 1
        otio_title["OpenTimelineIO"]
        otio1["Timeline"]
        otio2["Track"]
        otio3["Clip + TimeWarp"]
        otio4["纯数据模型"]
        space
    end

    block:gst:1
        columns 1
        gst_title["GStreamer"]
        gst1["src"]
        gst2["demux"]
        gst3["decode"]
        gst4["process"]
        gst5["sink + Seek Event"]
    end

    block:avf:1
        columns 1
        avf_title["AVFoundation"]
        avf1["AVAsset"]
        avf2["AVComposition"]
        avf3["AVPlayerItem"]
        avf4["AVPlayer"]
        space
    end

    style ff_title fill:#f44336,color:#fff
    style mlt_title fill:#9C27B0,color:#fff
    style otio_title fill:#3F51B5,color:#fff
    style gst_title fill:#009688,color:#fff
    style avf_title fill:#FF9800,color:#fff

flowchart TB
    subgraph Preview["实时预览管线"]
        direction LR
        P1["时间映射\nf(t)→Tm"] --> P2["解码器\n硬解优先"]
        P2 --> P3{"帧是否及时？"}
        P3 -->|是| P4["渲染合成"]
        P3 -->|否| P5["丢帧"]
        P4 --> P6["上屏 30/60fps"]
        P5 --> P6
    end

    subgraph Export["离线导出管线"]
        direction LR
        E1["时间映射\nf(t)→Tm"] --> E2["解码器\n可用软解"]
        E2 --> E3["渲染合成\n全分辨率"]
        E3 --> E4["编码器"]
        E4 --> E5["写入文件\n每帧必须"]
    end

    style Preview fill:#e3f2fd
    style Export fill:#fce4ec

flowchart TB
    SCENE{"时间特效场景"}
    SCENE -->|正向播放 + 均匀变速| HW["硬件解码器优先"]
    SCENE -->|倒放| DECIDE{"GOP 大小和设备能力"}
    SCENE -->|曲线变速跳跃大| SW["软件解码器可能更稳定"]
    SCENE -->|离线导出| SW2["可接受软解速度换取稳定性"]

    DECIDE -->|GOP 小 + 设备强| HW2["硬件解码器"]
    DECIDE -->|GOP 大 + 设备一般| SW3["软件解码器"]

mindmap
  root((时间特效设计决策))
    数据模型
      属性模式 vs Effect 对象 vs Wrapper
      是否支持曲线变速的原生表达
      时间轴时长是否随变速改变
    时间映射
      速度关键帧 vs 时间映射关键帧
      插值方式：线性 vs 贝塞尔
      预计算查表 vs 运行时计算
    解码执行
      全量缓冲 vs GOP 级缓冲 vs 预处理
      硬件解码 vs 软件解码
      关键帧索引：导入时构建 vs 运行时扫描
    音频处理
      是否保持音高
      变速算法选择
      音视频同步精度

gantt
    title 时间特效从零到生产级的实现路线
    dateFormat X
    axisFormat %s

    section 最小可用
    均匀变速        :done, p1a, 0, 2
    定格帧          :done, p1b, 0, 1
    帧重复式慢放     :done, p1c, 1, 2

    section 核心能力
    倒放 (GOP 级缓冲)  :active, p2a, 2, 6
    重复              :p2b, 4, 6
    关键帧索引         :p2c, 5, 7

    section 创作级
    曲线变速            :p3a, 7, 10
    音高补偿            :p3b, 8, 10
    帧插值              :p3c, 9, 12

    section 生产级
    异步解码管线         :p4a, 10, 13
    预解码缓冲池         :p4b, 11, 14
    硬解/软解自动切换     :p4c, 12, 14
    导出快速通道         :p4d, 13, 15

sequenceDiagram
    actor User as 用户
    participant UI as 编辑 UI
    participant Model as 数据模型
    participant Mapper as 时间映射
    participant Decoder as 解码器
    participant Buffer as GOP 缓冲
    participant Render as 渲染上屏

    User->>UI: 点击「倒放」
    UI->>Model: 修改 clip 时间特效属性
    Model->>Model: commit 生成快照，通知引擎
    Model->>Mapper: 模型更新通知

    loop 逐帧渲染（30/60fps）
        Mapper->>Mapper: 计算 f(t) = clip_end - t
        Mapper->>Decoder: 请求源素材时刻 Tm 的帧

        alt Tm 在当前 GOP 缓冲中
            Decoder->>Buffer: 缓冲命中
            Buffer->>Render: 返回帧纹理
        else Tm 超出当前 GOP
            Decoder->>Decoder: Seek 至新 GOP 的 I 帧
            Decoder->>Decoder: 正向解码整个 GOP
            Decoder->>Buffer: 缓存所有解码帧
            Buffer->>Render: 返回帧纹理
        end

        Render->>Render: GPU 合成
        Render->>User: 上屏显示
    end