flowchart LR
    subgraph Sender["发送端 Sender"]
        direction TB
        Capture["Capture\n采集"]
        PreProcess["PreProcess\n前处理/3A"]
        Encode["Encode\n编码"]
        Packetize["Packetize\nRTP 打包"]
        Pacer["Pacer\n平滑发送"]
    end

    subgraph Server["服务端 Server"]
        direction TB
        SFU["SFU\n选择性转发"]
        Router["Router\n路由/选层"]
        Bypass["Bypass\n旁路直播"]
    end

    subgraph Receiver["接收端 Receiver"]
        direction TB
        Depacketize["Depacketize\n解包"]
        JitterBuf["JitterBuffer\n抖动缓冲"]
        Decode["Decode\n解码"]
        Render["Render\n渲染"]
    end

    Capture --> PreProcess --> Encode --> Packetize --> Pacer
    Pacer -->|"RTP/SRTP"| SFU
    SFU --> Router
    Router -->|"RTP/SRTP"| Depacketize
    Router --> Bypass -->|"RTMP/CDN"| CDN["CDN\n10万观众"]
    Depacketize --> JitterBuf --> Decode --> Render

    Render -.->|"RTCP Feedback"| SFU
    SFU -.->|"RTCP/BWE"| Pacer

    classDef senderStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef serverStyle fill:#10B981,stroke:#047857,color:#fff
    classDef receiverStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef cdnStyle fill:#8B5CF6,stroke:#6D28D9,color:#fff

    class Capture,PreProcess,Encode,Packetize,Pacer senderStyle
    class SFU,Router,Bypass serverStyle
    class Depacketize,JitterBuf,Decode,Render receiverStyle
    class CDN cdnStyle

flowchart LR
    subgraph Control["控制面 Control Plane"]
        Auth["鉴权"]
        Signal["信令"]
        SDP["SDP 协商"]
        RoomMgmt["房间管理"]
    end

    subgraph Media["媒体面 Media Plane"]
        Cap["采集"]
        Enc["编码"]
        Trans["传输"]
        Dec["解码"]
        Rnd["渲染"]
    end

    subgraph Quality["质量面 Quality Plane"]
        BWE["带宽估计"]
        Adapt["码率自适应"]
        FeedbackLoop["RTCP 反馈"]
        Stats["指标观测"]
    end

    Control -.->|"建立/拆除"| Media
    Quality -.->|"调控"| Media
    Media -->|"统计数据"| Quality

    classDef controlStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef mediaStyle fill:#EC4899,stroke:#BE185D,color:#fff
    classDef qualityStyle fill:#14B8A6,stroke:#0D9488,color:#fff

    class Auth,Signal,SDP,RoomMgmt controlStyle
    class Cap,Enc,Trans,Dec,Rnd mediaStyle
    class BWE,Adapt,FeedbackLoop,Stats qualityStyle

flowchart TD
    UserIssue["🎯 用户反馈：卡顿"]

    UserIssue --> SendSide["发送端问题?"]
    UserIssue --> Network["网络问题?"]
    UserIssue --> ServerSide["服务端问题?"]
    UserIssue --> RecvSide["接收端问题?"]
    UserIssue --> BypassCDN["旁路CDN问题?"]

    SendSide --> CaptureIssue["采集掉帧\ncapture FPS 下降"]
    SendSide --> EncodeIssue["编码过慢\nencode queue 积压"]
    SendSide --> PacerIssue["Pacer 积压\nsend queue 过深"]

    Network --> PacketLoss["丢包\nloss rate > 5%"]
    Network --> Jitter["抖动\njitter > 50ms"]
    Network --> Congestion["拥塞\nBWE < target bitrate"]

    ServerSide --> SFUOverload["SFU 过载\nforwarding delay 高"]
    ServerSide --> LayerIssue["选层错误\n只转发低分辨率"]

    RecvSide --> JBStarving["JitterBuffer 饥饿\n无可用帧"]
    RecvSide --> DecodeBlock["解码阻塞\ndecode FPS 低"]
    RecvSide --> RenderDrop["渲染掉帧\nrender queue 丢帧"]

    BypassCDN --> CDNDelay["CDN 卡顿\n转码/分发延迟"]

    classDef issueStyle fill:#EF4444,stroke:#B91C1C,color:#fff
    classDef sendStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef netStyle fill:#8B5CF6,stroke:#6D28D9,color:#fff
    classDef srvStyle fill:#10B981,stroke:#047857,color:#fff
    classDef recvStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef cdnStyle fill:#EC4899,stroke:#BE185D,color:#fff

    class UserIssue issueStyle
    class SendSide,CaptureIssue,EncodeIssue,PacerIssue sendStyle
    class Network,PacketLoss,Jitter,Congestion netStyle
    class ServerSide,SFUOverload,LayerIssue srvStyle
    class RecvSide,JBStarving,DecodeBlock,RenderDrop recvStyle
    class BypassCDN,CDNDelay cdnStyle

erDiagram
    Room ||--o{ User : contains
    User ||--o{ Stream : publishes
    User ||--o{ Device : uses
    Stream ||--|{ Track : "has (audio/video)"
    Track ||--|| SSRC : "identified by"
    Track ||--|| Codec : "encoded with"
    User ||--o{ Subscription : subscribes
    Subscription }|--|| Track : "targets"
    SFU ||--o{ Room : serves
    SFU ||--o{ Track : forwards

    Room {
        string room_id
        string room_state
    }
    User {
        string user_id
        string role
    }
    Device {
        string device_id
        string device_type
    }
    Stream {
        string stream_id
        string stream_type
    }
    Track {
        string track_id
        string media_type
    }
    SSRC {
        int ssrc_value
        string direction
    }
    Codec {
        string codec_name
        string profile
    }
    Subscription {
        string sub_id
        string state
    }
    SFU {
        string sfu_id
        string region
    }

flowchart LR
    subgraph Room1["Room: live_room_001"]
        subgraph Host["主播 (host)"]
            HS["Stream: host_stream"]
            HV["Video Track\nSSRC=1001"]
            HA["Audio Track\nSSRC=1002"]
            HS --> HV
            HS --> HA
        end

        subgraph Guest1["嘉宾1"]
            G1S["Stream: guest1_stream"]
            G1V["Video Track\nSSRC=2001"]
            G1A["Audio Track\nSSRC=2002"]
            G1S --> G1V
            G1S --> G1A
        end

        subgraph Guest2["嘉宾2"]
            G2S["Stream: guest2_stream"]
            G2V["Video Track\nSSRC=3001"]
            G2A["Audio Track\nSSRC=3002"]
            G2S --> G2V
            G2S --> G2A
        end

        subgraph Guest3["嘉宾3"]
            G3S["Stream: guest3_stream"]
            G3V["Video Track\nSSRC=4001"]
            G3A["Audio Track\nSSRC=4002"]
            G3S --> G3V
            G3S --> G3A
        end
    end

    classDef hostStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef guestStyle fill:#10B981,stroke:#047857,color:#fff

    class HS,HV,HA hostStyle
    class G1S,G1V,G1A,G2S,G2V,G2A,G3S,G3V,G3A guestStyle

flowchart LR
    subgraph ControlPlane["控制面 Control Plane"]
        direction LR
        CS["发送端:\n鉴权/发布/SDP Offer"]
        CSrv["服务端:\n房间管理/路由决策"]
        CR["接收端:\n订阅/SDP Answer"]
    end

    subgraph MediaPlane["媒体面 Media Plane"]
        direction LR
        MS["发送端:\n采集→编码→打包→发送"]
        MSrv["服务端:\n转发/混流/转码"]
        MR["接收端:\n收包→组帧→解码→渲染"]
    end

    subgraph QualityPlane["质量面 Quality Plane"]
        direction LR
        QS["发送端:\n码率自适应/Pacer"]
        QSrv["服务端:\n选层/带宽分配"]
        QR["接收端:\nRTCP Feedback/Stats"]
    end

    classDef controlStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef mediaStyle fill:#EC4899,stroke:#BE185D,color:#fff
    classDef qualityStyle fill:#14B8A6,stroke:#0D9488,color:#fff

    class CS,CSrv,CR controlStyle
    class MS,MSrv,MR mediaStyle
    class QS,QSrv,QR qualityStyle

flowchart LR
    subgraph HostDevice["主播设备"]
        Camera["Camera"]
        Mic["Microphone"]
        VEnc["Video Encoder\nH.264 1080p"]
        AEnc["Audio Encoder\nOpus 48kHz"]
        Pack["RTP Packetizer"]
    end

    subgraph SFUCluster["SFU 集群"]
        Ingest["Ingest\n接收"]
        FwdEngine["Forwarding Engine\n转发引擎"]
        LayerSel["Layer Selection\n选层"]
        BypassMux["Bypass Muxer\n旁路封装"]
    end

    subgraph Guest["嘉宾设备"]
        Depack["Depacketizer"]
        VJB["Video JitterBuffer"]
        AJB["Audio JitterBuffer"]
        VDec["Video Decoder"]
        ADec["Audio Decoder"]
        AVSync["A/V Sync"]
        Screen["Screen Render"]
        Speaker["Audio Playout"]
    end

    subgraph CDNPath["CDN 旁路"]
        Transcoder["Transcoder"]
        CDNEdge["CDN Edge"]
        Audience["10万观众"]
    end

    Camera --> VEnc --> Pack
    Mic --> AEnc --> Pack
    Pack -->|"SRTP"| Ingest
    Ingest --> FwdEngine
    FwdEngine --> LayerSel
    LayerSel -->|"SRTP"| Depack
    FwdEngine --> BypassMux
    BypassMux --> Transcoder --> CDNEdge --> Audience
    Depack --> VJB --> VDec --> AVSync --> Screen
    Depack --> AJB --> ADec --> AVSync
    AVSync --> Speaker

    classDef senderStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef serverStyle fill:#10B981,stroke:#047857,color:#fff
    classDef receiverStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef cdnStyle fill:#8B5CF6,stroke:#6D28D9,color:#fff

    class Camera,Mic,VEnc,AEnc,Pack senderStyle
    class Ingest,FwdEngine,LayerSel,BypassMux serverStyle
    class Depack,VJB,AJB,VDec,ADec,AVSync,Screen,Speaker receiverStyle
    class Transcoder,CDNEdge,Audience cdnStyle

stateDiagram-v2
    direction LR
    [*] --> Idle
    Idle --> Joining: joinRoom()
    Joining --> Joined: join_success
    Joined --> Publishing: publish()
    Publishing --> Subscribing: subscribe()
    Subscribing --> FirstFrame: first_frame_rendered
    FirstFrame --> Playing: stable_playback
    Playing --> Reconnecting: connection_lost
    Reconnecting --> Joined: reconnect_success
    Reconnecting --> Idle: reconnect_failed
    Playing --> Leaving: leaveRoom()
    Leaving --> Idle: leave_complete
    Joined --> Leaving: leaveRoom()

sequenceDiagram
    participant App as App/UI
    participant SDK as RTC SDK
    participant Signal as Signal Server
    participant SFU as SFU/Media Server
    participant Publisher as Publisher SDK
    participant Decoder as Decoder
    participant Renderer as Renderer

    Note over App,Renderer: 首次入会到首帧 全流程

    App->>SDK: joinRoom(token, roomId)
    SDK->>Signal: authenticate(token)
    Signal-->>SDK: auth_success + room_info

    SDK->>Signal: join(roomId, userId)
    Signal-->>SDK: join_success + member_list + stream_list

    SDK->>Signal: subscribe(streamId, trackId)
    Signal->>SFU: setup_subscription(trackId, ssrc)
    Signal-->>SDK: subscribe_success

    SDK->>SFU: SDP Offer (codec, direction)
    SFU-->>SDK: SDP Answer

    Note over SDK,SFU: ICE Candidate Exchange
    SDK->>SFU: ICE candidates
    SFU-->>SDK: ICE candidates
    Note over SDK,SFU: Connectivity Check (STUN/TURN)
    SDK->>SFU: DTLS Handshake
    SFU-->>SDK: DTLS Complete

    Note over SFU,SDK: 媒体开始流动
    Publisher->>SFU: RTP packets (audio + video)
    SFU->>SDK: first RTP packet (audio)
    SFU->>SDK: first RTP packet (video)
    SFU->>SDK: more video RTP packets...
    SDK->>SDK: 组帧: assemble keyframe (IDR)
    SDK->>Decoder: decode(keyframe + SPS/PPS)
    Decoder-->>SDK: decoded_frame (YUV)
    SDK->>Renderer: render(frame)
    Renderer-->>App: first_frame_displayed ✅

gantt
    title TTFF（Time To First Frame）分段时间线
    dateFormat X
    axisFormat %s

    section 信令阶段
    auth           :a1, 0, 50
    join           :a2, after a1, 80
    subscribe      :a3, after a2, 60
    negotiate      :a4, after a3, 100

    section 连通阶段
    ICE            :b1, after a4, 120
    DTLS           :b2, after b1, 40

    section 媒体阶段
    first_pkt      :c1, after b2, 30
    keyframe       :c2, after c1, 80
    decode         :c3, after c2, 20
    render         :c4, after c3, 16

sequenceDiagram
    participant SDK as RTC SDK
    participant Signal as Signal Server
    participant SFU as SFU

    Note over SDK,SFU: 断线重连场景

    SDK->>SDK: detect connection_lost
    SDK->>Signal: reconnect(token, roomId, userId)
    Note over SDK,Signal: Token 未过期: 跳过完整鉴权
    Signal-->>SDK: reconnect_success + delta_state

    alt ICE Restart
        SDK->>SFU: ICE Restart (new candidates)
        SFU-->>SDK: ICE candidates
        Note over SDK,SFU: 新的 Connectivity Check
    else 复用连接
        Note over SDK,SFU: 连接仍存活, 直接恢复
    end

    SDK->>SFU: PLI/FIR (请求新关键帧)
    SFU->>SDK: new IDR frame
    Note over SDK: JitterBuffer 重置
    SDK->>SDK: decode new IDR
    SDK->>SDK: render → 画面恢复 ✅

sequenceDiagram
    participant App as Client App
    participant SDK as RTC SDK
    participant Signal as Signal Server
    participant SFU as SFU

    Note over App,SFU: 完整信令生命周期

    rect rgb(219, 234, 254)
        Note right of App: 鉴权与进房
        App->>SDK: joinRoom(token, config)
        SDK->>Signal: auth(token)
        Signal-->>SDK: auth_ok(room_info, member_list)
        SDK-->>App: onJoinSuccess(room)
    end

    rect rgb(220, 252, 231)
        Note right of App: 发布
        App->>SDK: publish(localStream)
        SDK->>Signal: publish(stream_id, tracks)
        Signal->>SFU: allocate_publisher(ssrc_map)
        Signal-->>SDK: publish_success
        SDK-->>App: onPublishSuccess()
        Note over Signal: 广播 stream_added 给其他成员
    end

    rect rgb(254, 243, 199)
        Note right of App: 订阅
        Signal-->>SDK: onStreamAdded(remote_stream)
        SDK-->>App: onRemoteStreamAdded(stream)
        App->>SDK: subscribe(remote_stream)
        SDK->>Signal: subscribe(stream_id, track_ids)
        Signal->>SFU: setup_forward(ssrc, target)
        Signal-->>SDK: subscribe_success
    end

    rect rgb(254, 226, 226)
        Note right of App: 退会
        App->>SDK: leaveRoom()
        SDK->>Signal: leave(room_id)
        Signal->>SFU: cleanup(user_id)
        Signal-->>SDK: leave_success
        Note over Signal: 广播 member_left 给其他成员
    end

stateDiagram-v2
    direction LR
    [*] --> Disconnected
    Disconnected --> Connecting: connect()
    Connecting --> Connected: ws_open
    Connected --> Joining: joinRoom()
    Joining --> Joined: join_success
    Joining --> Connected: join_failed
    Joined --> Leaving: leaveRoom()
    Leaving --> Connected: leave_done
    Connected --> Disconnected: ws_close
    Joined --> Reconnecting: connection_lost
    Reconnecting --> Joined: reconnect_ok
    Reconnecting --> Disconnected: reconnect_failed

flowchart TD
    subgraph SimulcastFlow["Simulcast 模式"]
        Encoder1["Encoder x3"]
        High["High: 1080p 30fps\n2.5Mbps"]
        Mid["Mid: 720p 30fps\n1Mbps"]
        Low["Low: 360p 15fps\n300Kbps"]
        Encoder1 --> High
        Encoder1 --> Mid
        Encoder1 --> Low

        SFU1["SFU\n选流转发"]
        High --> SFU1
        Mid --> SFU1
        Low --> SFU1

        SFU1 -->|"High"| RecvA["接收端A\n带宽充足"]
        SFU1 -->|"Low"| RecvB["接收端B\n带宽受限"]
    end

    classDef senderStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef serverStyle fill:#10B981,stroke:#047857,color:#fff
    classDef receiverStyle fill:#F59E0B,stroke:#D97706,color:#fff

    class Encoder1,High,Mid,Low senderStyle
    class SFU1 serverStyle
    class RecvA,RecvB receiverStyle

flowchart LR
    subgraph Handshake["DTLS 握手"]
        ClientHello["Client Hello"]
        ServerHello["Server Hello\n+ Certificate"]
        KeyExchange["Key Exchange"]
        Finished["Finished\n密钥协商完成"]
        ClientHello --> ServerHello --> KeyExchange --> Finished
    end

    subgraph Encryption["SRTP 加密传输"]
        RTPIn["RTP Packet\n(明文 payload)"]
        SRTPOut["SRTP Packet\n(加密 payload)"]
        RTPIn -->|"AES-128-CM"| SRTPOut
    end

    Finished -->|"导出 SRTP 密钥"| RTPIn

    classDef handshakeStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef encStyle fill:#10B981,stroke:#047857,color:#fff

    class ClientHello,ServerHello,KeyExchange,Finished handshakeStyle
    class RTPIn,SRTPOut encStyle

flowchart TD
    Start["ICE 启动"]
    GatherHost["收集 Host Candidate\n(本机 IP)"]
    GatherSrflx["查询 STUN Server\n获取 Srflx Candidate\n(NAT 映射 IP)"]
    GatherRelay["分配 TURN Server\n获取 Relay Candidate\n(中继 IP)"]

    Start --> GatherHost
    Start --> GatherSrflx
    Start --> GatherRelay

    PairUp["生成 Candidate Pairs\n(本端 × 对端)"]
    GatherHost --> PairUp
    GatherSrflx --> PairUp
    GatherRelay --> PairUp

    Check["Connectivity Check\n(STUN Binding Request)"]
    PairUp --> Check

    Check -->|成功| Nominate["Nominate Best Pair"]
    Check -->|失败| TryNext["尝试下一个 Pair"]
    TryNext --> Check

    Nominate --> Connected["ICE Connected ✅"]

    Check -->|所有 Pair 失败| Failed["ICE Failed ❌"]

    classDef startStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef gatherStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef checkStyle fill:#10B981,stroke:#047857,color:#fff
    classDef resultStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef failStyle fill:#EF4444,stroke:#B91C1C,color:#fff

    class Start startStyle
    class GatherHost,GatherSrflx,GatherRelay gatherStyle
    class PairUp,Check,TryNext checkStyle
    class Nominate,Connected resultStyle
    class Failed failStyle

stateDiagram-v2
    direction LR
    [*] --> New
    New --> Gathering: start
    Gathering --> Checking: candidates_ready
    Checking --> Connected: pair_succeeded
    Connected --> Completed: nomination_done
    Checking --> Failed: all_pairs_failed
    Completed --> Disconnected: connectivity_lost
    Disconnected --> Checking: restart

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V=2|P|X|  CC   |M|     PT      |       Sequence Number         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           Timestamp                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                             SSRC                              |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                        Payload (encoded media)                |
|                             ...                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

flowchart LR
    Frame["Encoded Frame\n(50KB IDR)"]
    P1["RTP #101\n1200B"]
    P2["RTP #102\n1200B"]
    P3["RTP #103\n1200B"]
    Dots["..."]
    P42["RTP #142\n(M=1)\n800B"]

    Frame --> P1
    Frame --> P2
    Frame --> P3
    Frame --> Dots
    Frame --> P42

    P1 -->|网络传输| Reassemble["接收端组帧"]
    P2 --> Reassemble
    P3 --> Reassemble
    Dots --> Reassemble
    P42 --> Reassemble

    Reassemble -->|所有包到齐| DecodableFrame["完整帧\n可解码 ✅"]
    Reassemble -->|缺包| IncompleteFrame["不完整帧\n无法解码 ❌"]

    classDef senderStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef receiverStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef okStyle fill:#10B981,stroke:#047857,color:#fff
    classDef failStyle fill:#EF4444,stroke:#B91C1C,color:#fff

    class Frame,P1,P2,P3,Dots,P42 senderStyle
    class Reassemble receiverStyle
    class DecodableFrame okStyle
    class IncompleteFrame failStyle

sequenceDiagram
    participant Sender as 发送端
    participant SFU as SFU
    participant Receiver as 接收端

    Sender->>SFU: RTP packets (video)
    SFU->>Receiver: RTP packets (forwarded)

    Note over Receiver: 检测到 seq #105 丢失
    Receiver->>SFU: NACK (seq=105)
    SFU->>Sender: NACK relay (seq=105)
    Sender->>SFU: RTX (retransmit seq=105)
    SFU->>Receiver: RTX (seq=105)

    Note over Receiver: 帧组装恢复

    Sender->>SFU: RTCP SR (RTP_ts ↔ NTP)
    SFU->>Receiver: RTCP SR (forwarded)
    Note over Receiver: 更新音画同步基准

    Receiver->>SFU: RTCP RR (loss=2%, jitter=15ms)
    SFU->>Sender: RTCP RR
    Note over Sender: 调整码率策略

    Receiver->>SFU: Transport-CC (packet arrival times)
    SFU->>Sender: Transport-CC
    Note over Sender: 基于延迟梯度估计带宽

flowchart LR
    subgraph Mesh["Mesh/P2P"]
        MA["A"] <-->|直连| MB["B"]
        MA <-->|直连| MC["C"]
        MB <-->|直连| MC
    end

    subgraph StarTURN["TURN Relay"]
        TA["A"] -->|relay| TURN["TURN Server"]
        TB["B"] -->|relay| TURN
        TURN -->|relay| TA
        TURN -->|relay| TB
    end

    subgraph StarSFU["SFU"]
        SA["A"] -->|1路上行| SFU1["SFU"]
        SB["B"] -->|1路上行| SFU1
        SC["C"] -->|1路上行| SFU1
        SFU1 -->|N路下行| SA
        SFU1 -->|N路下行| SB
        SFU1 -->|N路下行| SC
    end

    subgraph StarMCU["MCU"]
        MA2["A"] -->|1路上行| MCU1["MCU\n解码+混流+编码"]
        MB2["B"] -->|1路上行| MCU1
        MCU1 -->|1路混合下行| MA2
        MCU1 -->|1路混合下行| MB2
    end

flowchart LR
    Publisher1["主播\nSSRC=1001(V)\nSSRC=1002(A)"]
    Publisher2["嘉宾1\nSSRC=2001(V)\nSSRC=2002(A)"]
    Publisher3["嘉宾2\nSSRC=3001(V)\nSSRC=3002(A)"]

    SFU["SFU\nForwarding Engine"]

    Sub1["嘉宾1\n订阅: 主播+嘉宾2"]
    Sub2["嘉宾2\n订阅: 主播+嘉宾1"]
    Sub3["嘉宾3\n订阅: 主播+嘉宾1+嘉宾2"]

    Publisher1 -->|"V:1001 A:1002"| SFU
    Publisher2 -->|"V:2001 A:2002"| SFU
    Publisher3 -->|"V:3001 A:3002"| SFU

    SFU -->|"1001+1002\n3001+3002"| Sub1
    SFU -->|"1001+1002\n2001+2002"| Sub2
    SFU -->|"1001+1002\n2001+2002\n3001+3002"| Sub3

    classDef senderStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef serverStyle fill:#10B981,stroke:#047857,color:#fff
    classDef receiverStyle fill:#F59E0B,stroke:#D97706,color:#fff

    class Publisher1,Publisher2,Publisher3 senderStyle
    class SFU serverStyle
    class Sub1,Sub2,Sub3 receiverStyle

flowchart LR
    subgraph Beijing["北京区域"]
        Host["主播\n北京"]
        SFU_BJ["SFU-Beijing"]
        Host --> SFU_BJ
    end

    subgraph Shanghai["上海区域"]
        Guest1["嘉宾1\n上海"]
        SFU_SH["SFU-Shanghai"]
        SFU_SH --> Guest1
    end

    subgraph US["美西区域"]
        Guest2["嘉宾2\n美西"]
        SFU_US["SFU-US-West"]
        SFU_US --> Guest2
    end

    SFU_BJ <-->|"Cascade\n内部网络"| SFU_SH
    SFU_BJ <-->|"Cascade\n内部网络"| SFU_US

    classDef bjStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef shStyle fill:#10B981,stroke:#047857,color:#fff
    classDef usStyle fill:#F59E0B,stroke:#D97706,color:#fff

    class Host,SFU_BJ bjStyle
    class Guest1,SFU_SH shStyle
    class Guest2,SFU_US usStyle

flowchart LR
    subgraph RTCZone["RTC 区域 (<400ms)"]
        Host["主播"]
        G1["嘉宾1"]
        G2["嘉宾2"]
        G3["嘉宾3"]
        SFU["SFU"]
        Host <-->|RTP| SFU
        G1 <-->|RTP| SFU
        G2 <-->|RTP| SFU
        G3 <-->|RTP| SFU
    end

    subgraph BypassZone["旁路服务"]
        Mixer["Mixer\n混流"]
        Transcoder["Transcoder\n转码"]
    end

    subgraph CDNZone["CDN 区域 (1-5s)"]
        Origin["CDN Origin"]
        Edge1["Edge Node 1"]
        Edge2["Edge Node 2"]
        EdgeN["Edge Node N"]
        Audience["10万观众"]
    end

    SFU -->|"抽取 RTP"| Mixer
    Mixer -->|"混合画面"| Transcoder
    Transcoder -->|"RTMP/SRT"| Origin
    Origin --> Edge1 --> Audience
    Origin --> Edge2 --> Audience
    Origin --> EdgeN --> Audience

    classDef rtcStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef bypassStyle fill:#10B981,stroke:#047857,color:#fff
    classDef cdnStyle fill:#F59E0B,stroke:#D97706,color:#fff

    class Host,G1,G2,G3,SFU rtcStyle
    class Mixer,Transcoder bypassStyle
    class Origin,Edge1,Edge2,EdgeN,Audience cdnStyle

flowchart TD
    subgraph VideoPipeline["视频发送链路"]
        CamCapture["Camera Capture\n前/后摄 1080p 30fps"]
        ScreenCapture["Screen Capture\n屏幕共享"]
        CustomCapture["Custom Source\n游戏画面/外接设备"]

        CamCapture --> Crop["Crop / Scale / Rotate\n裁剪/缩放/旋转"]
        ScreenCapture --> Crop
        CustomCapture --> Crop

        Crop --> Beauty["Beauty / Filter\n美颜/滤镜\n(可选)"]
        Beauty --> VEncoder["Video Encoder\nH.264 High Profile\n硬编优先"]

        VEncoder --> SimLayer["Simulcast\n(可选多层编码)"]
        SimLayer --> RTPPack["RTP Packetizer\n分包 + SSRC + Timestamp"]
        RTPPack --> Pacer["Pacer\n平滑发送"]
        Pacer --> Network["Network\nSRTP → SFU"]
    end

    classDef captureStyle fill:#60A5FA,stroke:#2563EB,color:#fff
    classDef processStyle fill:#818CF8,stroke:#4F46E5,color:#fff
    classDef encodeStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef sendStyle fill:#2563EB,stroke:#1E3A8A,color:#fff

    class CamCapture,ScreenCapture,CustomCapture captureStyle
    class Crop,Beauty processStyle
    class VEncoder,SimLayer,RTPPack encodeStyle
    class Pacer,Network sendStyle

flowchart LR
    Mic["Microphone\n麦克风采集"]
    AEC["AEC\n回声消除"]
    NS["NS/ANS\n降噪"]
    AGC["AGC\n自动增益"]
    AEncoder["Audio Encoder\nOpus 48kHz stereo"]
    ARTPPack["RTP Packetizer"]

    Mic --> AEC --> NS --> AGC --> AEncoder --> ARTPPack

    FarEnd["远端音频\n(参考信号)"]
    FarEnd -.->|参考| AEC

    classDef audioStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef refStyle fill:#9CA3AF,stroke:#6B7280,color:#fff

    class Mic,AEC,NS,AGC,AEncoder,ARTPPack audioStyle
    class FarEnd refStyle

def pacer_send(encoded_frame, target_bitrate):
    packets = packetize(encoded_frame)
    send_interval = packet_size / target_bitrate

    for packet in packets:
        send(packet)
        wait(send_interval)  # 匀速释放，避免突发

flowchart TD
    subgraph RecvPipeline["接收端链路"]
        RTPIn["RTP Packets\n(from network)"]
        Dedup["Dedup & Reorder\n去重/排序"]
        Assemble["Frame Assembly\n组帧"]

        RTPIn --> Dedup --> Assemble

        Assemble -->|完整帧| VJB["Video JitterBuffer"]
        Assemble -->|缺包| NACK_Req["发 NACK 请求重传"]
        NACK_Req -.->|RTX 到达| Assemble

        VJB --> TargetDelay{"到达 target\nplayout time?"}
        TargetDelay -->|是| VDec["Video Decoder\n(硬解/软解)"]
        TargetDelay -->|太早| Wait["等待"]
        Wait --> TargetDelay
        TargetDelay -->|太晚| Drop["丢弃 late frame"]

        VDec --> PostProcess["Post-Process\n旋转/缩放/色彩转换"]
        PostProcess --> Render["Render to Screen"]
    end

    classDef recvStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef decisionStyle fill:#EF4444,stroke:#B91C1C,color:#fff

    class RTPIn,Dedup,Assemble,VJB,VDec,PostProcess,Render recvStyle
    class TargetDelay,Wait,Drop,NACK_Req decisionStyle

stateDiagram-v2
    direction LR
    [*] --> Buffering: 开始接收
    Buffering --> Playing: buffer_level >= target_delay
    Playing --> Starving: buffer_level == 0
    Starving --> Recovering: 收到新帧
    Recovering --> Playing: buffer_level >= min_threshold
    Starving --> WaitIDR: 连续丢帧超阈值
    WaitIDR --> Recovering: 收到 IDR

时间轴 →

包到达时间:     |  p1  |    p2    |p3|       p4        |  p5  |
                ↓      ↓          ↓  ↓                 ↓      ↓
JitterBuffer:   [======|==========|==|=================|======]
                       ↑ target_delay ↑
                       |              |
播放时间:       -------|---f1---|---f2---|---f3---|---f4---|---f5---
                       ↑                                ↑
                   start_play                       current_play

                抖动越大 → target_delay 越大 → 延迟越高
                target_delay 越小 → 抗抖动能力弱 → 容易 starving → 卡顿

class JitterBuffer:
    def __init__(self):
        self.buffer = {}        # timestamp -> frame
        self.target_delay = 80  # ms, 动态调整
        self.state = "buffering"

    def on_packet(self, packet):
        frame = self.assemble(packet)
        if not frame:
            return  # 帧未组装完成

        if frame.is_too_late(self.current_play_time, self.late_threshold):
            self.stats.record("late_frame_dropped")
            return  # 帧到达太晚，直接丢弃

        self.buffer[frame.timestamp] = frame
        self._update_target_delay(packet.arrival_jitter)

        if self.state == "buffering":
            if self.buffer_level() >= self.target_delay:
                self.state = "playing"

    def get_next_frame(self, current_time):
        if self.state != "playing":
            return None

        next_ts = self.next_playout_timestamp()
        if next_ts in self.buffer:
            frame = self.buffer.pop(next_ts)
            return frame
        else:
            self.stats.record("freeze")
            self.state = "starving"
            return None  # 卡顿！

    def _update_target_delay(self, jitter):
        # 动态调整: 抖动大则增大 buffer, 抖动小则减小
        self.target_delay = clamp(
            self.target_delay * 0.95 + jitter * 2 * 0.05,
            min=20, max=500
        )

GOP (Group of Pictures) 结构示意:

|  IDR  |  P  |  P  |  P  |  P  |  P  |  ...  |  P  |  IDR  |  P  |  P  | ...
|<--------------------- GOP = 30~60 frames ---------------------->|<-- next GOP -->|
      ↑                                                                  ↑
   关键帧: 可独立解码                                              新的解码起点

flowchart LR
    IDR["IDR\n可独立解码"]
    P1["P1\n依赖 IDR"]
    P2["P2\n依赖 P1"]
    P3["P3\n依赖 P2"]
    P4["P4\n依赖 P3"]

    IDR --> P1 --> P2 --> P3 --> P4

    P2 -.-x|"丢失!"| LostMark["❌"]

    style LostMark fill:#EF4444,stroke:#B91C1C,color:#fff

    P3 -.-|"P2 丢失\n→ P3 无法解码\n→ P4 也无法解码"| Cascade["参考链断裂\n后续帧全部受影响"]

    classDef normalStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef lostStyle fill:#EF4444,stroke:#B91C1C,color:#fff

    class IDR,P1,P4 normalStyle

端到端延迟 = 各队列等待时间之和

Capture  →  Encode    →  Pacer     →  Network   →  JitterBuf  →  Decode  →  Render
(5ms)       (10-30ms)    (10-50ms)    (20-100ms)    (20-200ms)    (5-20ms)   (16ms)

|<--- 发送端 ~25-85ms --->|<-- 网络 -->|<-------- 接收端 ~40-236ms -------->|
|<------------------------- 总计: 85-420ms ----------------------------->|

flowchart TD
    CaptureTime["Capture Time\n采集时刻 (system clock)"]
    RTPTimestamp["RTP Timestamp\n编码时间戳 (codec clock)"]
    RTCPSR["RTCP Sender Report\nRTP_ts ↔ NTP 映射"]
    NTPTime["NTP Time\n绝对时间"]
    AudioClock["Audio Playout Clock\n音频播放时钟"]
    RenderTime["Video Render Time\n视频渲染时刻"]
    AVSyncDecision["A/V Sync Decision\n音画同步决策"]

    CaptureTime -->|"编码器打 RTP ts"| RTPTimestamp
    RTPTimestamp -->|"发送端通过 SR 报告"| RTCPSR
    RTCPSR -->|"接收端换算"| NTPTime
    NTPTime -->|"映射到播放时间轴"| RenderTime
    NTPTime -->|"映射到播放时间轴"| AudioClock
    AudioClock -->|"audio 作为主时钟"| AVSyncDecision
    RenderTime -->|"video 对齐到 audio"| AVSyncDecision

    classDef timeStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef syncStyle fill:#10B981,stroke:#047857,color:#fff

    class CaptureTime,RTPTimestamp,RTCPSR,NTPTime timeStyle
    class AudioClock,RenderTime,AVSyncDecision syncStyle

def av_sync_decision(video_frame, audio_playout_time):
    """
    以音频播放时钟为基准，决定视频帧的处理方式
    """
    delta = video_frame.pts - audio_playout_time  # 正 = 视频超前，负 = 视频落后

    EARLY_THRESHOLD = 40   # ms, 视频超前容忍上限
    LATE_THRESHOLD = -80   # ms, 视频落后容忍上限

    if delta > EARLY_THRESHOLD:
        # 视频太早: 等待，不急着渲染
        schedule_render(video_frame, delay=delta)
    elif delta < LATE_THRESHOLD:
        # 视频太晚: 丢弃或快进，赶上音频
        drop_frame(video_frame)
        stats.record("sync_drop")
    else:
        # 可接受范围: 立即渲染
        render_immediately(video_frame)

A/V Sync 时间线示意:

Audio playout:  |--a1--|--a2--|--a3--|--a4--|--a5--|--a6--|--a7--|
                ↑ 主时钟

Video frames:   太早        正常     正常   太晚          正常
                |--v1--|     |--v2--|--v3--|    |--v4--|  |--v5--|
                ↓ wait       ↓ render      ↓ drop        ↓ render

flowchart LR
    subgraph ReceiverSide["接收端"]
        Stats["Stats Collection\n丢包率/抖动/RTT"]
        Feedback["RTCP Feedback\nRR/Transport-CC/NACK"]
    end

    subgraph Network["网络"]
        NetPath["Network Path"]
    end

    subgraph SenderSide["发送端"]
        BWE["Bandwidth Estimator\n带宽估计"]
        Controller["Rate Controller\n码率/帧率/分辨率决策"]
        Encoder["Encoder\n执行调整"]
        Pacer2["Pacer\n平滑发送"]
    end

    subgraph ServerSide["服务端"]
        LayerSelect["Layer Selection\n选层"]
    end

    Stats --> Feedback
    Feedback -->|"RTCP"| NetPath
    NetPath --> BWE
    BWE --> Controller
    Controller --> Encoder
    Encoder --> Pacer2
    Pacer2 -->|"RTP"| NetPath
    NetPath --> Stats

    Feedback -->|"Transport-CC"| LayerSelect
    LayerSelect -->|"选择转发层"| NetPath

    classDef recvStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef netStyle fill:#8B5CF6,stroke:#6D28D9,color:#fff
    classDef sendStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef srvStyle fill:#10B981,stroke:#047857,color:#fff

    class Stats,Feedback recvStyle
    class NetPath netStyle
    class BWE,Controller,Encoder,Pacer2 sendStyle
    class LayerSelect srvStyle

sequenceDiagram
    participant Receiver as 接收端
    participant SFU as SFU
    participant Sender as 发送端

    Note over Receiver,Sender: QoS 闭环一次完整循环

    Receiver->>Receiver: 检测丢包率=5%, jitter=40ms
    Receiver->>SFU: Transport-CC (每包到达时间)
    Receiver->>SFU: RTCP RR (loss=5%)
    SFU->>Sender: 转发 Transport-CC + RR

    Note over Sender: 带宽估计: 2Mbps → 1.2Mbps
    Sender->>Sender: 降码率 2Mbps → 1Mbps
    Sender->>Sender: 降帧率 30fps → 20fps
    Sender->>SFU: 更新 RTP 流 (低码率)

    SFU->>SFU: 切换 Simulcast 层 High → Mid
    SFU->>Receiver: 转发 Mid 层 (720p)

    Note over Receiver: 丢包率下降到 1%
    Receiver->>SFU: Transport-CC (改善)
    SFU->>Sender: 转发

    Note over Sender: 带宽估计回升: 1.2Mbps → 1.8Mbps
    Sender->>Sender: 逐步升码率

def adapt(estimated_bw, current_bitrate, loss_rate, rtt):
    """
    码率自适应策略: 分级降级，逐步恢复
    """
    if estimated_bw < current_bitrate * 0.8:
        # 第一级: 降码率
        new_bitrate = estimated_bw * 0.85
        set_encoder_bitrate(new_bitrate)

        if still_overloaded(loss_rate > 0.05):
            # 第二级: 降帧率
            reduce_fps(target=15)

            if still_overloaded(loss_rate > 0.10):
                # 第三级: 降分辨率
                reduce_resolution(factor=0.5)

    elif estimated_bw > current_bitrate * 1.3 and loss_rate < 0.02:
        # 恢复: 保守上探
        new_bitrate = min(current_bitrate * 1.1, estimated_bw * 0.85, max_bitrate)
        set_encoder_bitrate(new_bitrate)
        # 帧率和分辨率恢复更慢，避免震荡

flowchart TD
    Start["丢包检测"]
    RTTCheck{"RTT < 150ms?"}
    LossCheck{"丢包率 < 10%?"}
    FECCheck{"可预测丢包模式?"}

    Start --> RTTCheck
    RTTCheck -->|是| LossCheck
    RTTCheck -->|否| FEC["优先 FEC\n(NACK RTX 可能来不及)"]

    LossCheck -->|是| NACK["NACK + RTX\n(精准修复)"]
    LossCheck -->|否| FECCheck

    FECCheck -->|是| FECAdaptive["自适应 FEC\n(根据丢包模式调冗余度)"]
    FECCheck -->|否| Hybrid["NACK + FEC 混合\n+ PLI 兜底"]

    classDef decisionStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef actionStyle fill:#10B981,stroke:#047857,color:#fff

    class Start,RTTCheck,LossCheck,FECCheck decisionStyle
    class NACK,FEC,FECAdaptive,Hybrid actionStyle

flowchart TD
    DecodedFrame["Decoded Frame\n(YUV 420P / NV12)"]
    TextureUpload["Texture Upload\nCPU→GPU"]
    Shader["Shader Processing\nYUV→RGB 转换\n旋转/镜像/缩放"]
    Composite["Compositing\n与其他 UI 合成"]
    Display["Display\nScreen Output"]

    DecodedFrame --> TextureUpload --> Shader --> Composite --> Display

    DecodedFrame -->|"零拷贝路径"| ZeroCopy["Direct Texture\n(CVPixelBuffer/\nHardwareBuffer)"]
    ZeroCopy --> Shader

    classDef normalStyle fill:#F59E0B,stroke:#D97706,color:#fff
    classDef fastStyle fill:#10B981,stroke:#047857,color:#fff

    class DecodedFrame,TextureUpload,Shader,Composite,Display normalStyle
    class ZeroCopy fastStyle

stateDiagram-v2
    direction LR
    [*] --> Idle: SDK 初始化完成
    Idle --> Joining: joinRoom()
    Joining --> Joined: join_success
    Joining --> Idle: join_failed

    state Joined {
        [*] --> Ready
        Ready --> Publishing: publish()
        Publishing --> Published: publish_ok
        Published --> Unpublishing: unpublish()
        Unpublishing --> Ready: unpublish_ok
        Ready --> Subscribing: subscribe()
        Subscribing --> Subscribed: subscribe_ok
        Subscribed --> Unsubscribing: unsubscribe()
        Unsubscribing --> Ready: unsubscribe_ok
    }

    Joined --> Reconnecting: connection_lost
    Reconnecting --> Joined: reconnect_ok
    Reconnecting --> Idle: reconnect_failed
    Joined --> Leaving: leaveRoom()
    Leaving --> Idle: leave_done

flowchart TD
    subgraph Threads["典型 RTC SDK 线程模型"]
        APIThread["API Thread\n(主线程)\n处理 App 调用"]
        SignalThread["Signal Thread\n信令收发和状态机"]
        NetworkThread["Network Thread\nRTP/RTCP 收发"]
        EncodeThread["Encode Thread\n视频/音频编码"]
        DecodeThread["Decode Thread\n视频/音频解码"]
        RenderThread["Render Thread\n视频渲染\n(OpenGL/Metal)"]
        AudioThread["Audio Thread\n音频采集/播放\n(实时优先级)"]
    end

    APIThread -->|"command queue"| SignalThread
    SignalThread -->|"notify"| APIThread
    SignalThread -->|"setup"| NetworkThread
    NetworkThread -->|"encoded data"| EncodeThread
    NetworkThread -->|"RTP packets"| DecodeThread
    DecodeThread -->|"decoded frames"| RenderThread
    AudioThread <-->|"PCM data"| EncodeThread
    AudioThread <-->|"PCM data"| DecodeThread

    classDef apiStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef mediaStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef renderStyle fill:#F59E0B,stroke:#D97706,color:#fff

    class APIThread apiStyle
    class SignalThread,NetworkThread,EncodeThread,DecodeThread mediaStyle
    class RenderThread,AudioThread renderStyle

App 调用 publish()
  → API Thread 接收
  → 放入 Command Queue
  → Signal Thread 从队列取出
  → 发送信令
  → 等待服务端响应
  → 触发回调 onPublishSuccess / onPublishFailed

flowchart LR
    CallID["call_id\n(一次通话)"]
    RoomID["room_id\n(一个房间)"]
    UserID["user_id\n(一个参与者)"]
    StreamID["stream_id\n(一路流)"]
    TrackID["track_id\n(一路音频/视频)"]
    SSRC_ID["ssrc\n(RTP 层标识)"]

    CallID --> RoomID --> UserID --> StreamID --> TrackID --> SSRC_ID

    classDef idStyle fill:#6366F1,stroke:#4338CA,color:#fff
    class CallID,RoomID,UserID,StreamID,TrackID,SSRC_ID idStyle

flowchart TD
    subgraph RTC["RTC 四面模型"]
        Control["控制面\n谁能通信?\n信令/鉴权/SDP"]
        Media["媒体面\n数据怎么流?\n采集→编码→传输→解码→渲染"]
        Quality["质量面\n体验好不好?\n弱网控制/码率自适应"]
        Observe["观测面\n能不能查?\n指标/日志/Trace"]
    end

    Control -->|"建立"| Media
    Quality -->|"调控"| Media
    Media -->|"数据"| Quality
    Observe -.->|"监控"| Control
    Observe -.->|"监控"| Media
    Observe -.->|"监控"| Quality

    classDef controlStyle fill:#6366F1,stroke:#4338CA,color:#fff
    classDef mediaStyle fill:#3B82F6,stroke:#1E40AF,color:#fff
    classDef qualityStyle fill:#10B981,stroke:#047857,color:#fff
    classDef observeStyle fill:#F59E0B,stroke:#D97706,color:#fff

    class Control controlStyle
    class Media mediaStyle
    class Quality qualityStyle
    class Observe observeStyle