Agora SEI 메타데이터 — H.264·H.265 Payload 해석

[발신측]
   │
   ├─ 비디오 프레임 t=10.0s ──→ [네트워크] ──→ [시청자] (예: 12.3s 도착, 합성된 화면)
   │
   └─ 시그널링 메시지 ──────→ [네트워크] ──→ [시청자] (예: 12.1s 또는 12.7s 도착, 별도 채널)

[발신측]
   │
   └─ NAL 스트림: [SEI: 레이아웃] [Slice: 비디오] ──→ [네트워크] ──→ [시청자]
                                                                       └─ 같은 bitstream에서 해석

{
  "canvas":   { ... 캔버스 정보 ... },
  "regions":  [ ... 호스트별 레이아웃 ... ],
  "ver":      20190611,
  "ts":       1683195420123,
  "app_data": "사용자 정의"
}

{
  "canvas": {
    "w": 1920,
    "h": 1080,
    "bgnd": "#000000"
  },
  "regions": [
    {
      "uid": 1001,
      "x": 0, "y": 0, "w": 960, "h": 540,
      "alpha": 1.0, "zorder": 1, "volume": 50
    },
    {
      "uid": 1002,
      "x": 960, "y": 0, "w": 960, "h": 540,
      "alpha": 1.0, "zorder": 1, "volume": 50
    },
    {
      "uid": 1003,
      "x": 0, "y": 540, "w": 1920, "h": 540,
      "alpha": 1.0, "zorder": 1, "volume": 50
    }
  ],
  "ver": "20190611",
  "ts": 1683195420123,
  "app_data": "{\"chapter\":\"intro\"}"
}

06 64 bd [...JSON content...]

0x06 = 0000 0110
       │ ││ │└┴┴── nal_unit_type (5 bits) = 0b00110 = 6 → SEI
       │ └┴── nal_ref_idc (2 bits) = 0 (SEI는 비참조)
       └── forbidden_zero_bit = 0

[Slice: 프레임 N-1] [SEI: payload] [Slice: 프레임 N] [Slice: 프레임 N+1]
                    ↑ 프레임 N과 묶여서 도착

length = 0;
byte = read_byte();
while (byte == 0xFF) {
    length += 255;
    byte = read_byte();
}
length += byte;

def read_variable_length(buf, pos):
    length = 0
    while buf[pos] == 0xFF:
        length += 255
        pos += 1
    length += buf[pos]
    pos += 1
    return length, pos

# SEI 시작 위치(NAL 헤더 다음)에서:
payload_type, pos = read_variable_length(buf, pos)
payload_size, pos = read_variable_length(buf, pos)
payload = buf[pos:pos + payload_size]

[start code: 00 00 00 01] [NAL header: 06] [payload_type] [payload_size] [payload]

[length: 4 bytes big-endian] [NAL header: 06] [payload_type] [payload_size] [payload]

[RTMP 도착]
   ↓
FLV 디먹스 → AVCC 포맷 NAL 단위 추출
   ↓
[NAL: 06 64 bd ... ]
   ↓
첫 바이트 0x06 → SEI NAL
   ↓
payload_type 읽기 (0xFF 누적)
   ↓
payload_type == 100? (Agora 커스텀)
   ↓ Yes
payload_size 읽기 (0xFF 누적)
   ↓
payload bytes (= JSON 문자열)
   ↓
JSON.parse
   ↓
canvas / regions / ver / ts / app_data 추출
   ↓
UI 업데이트 (예: 클릭 가능 영역 매핑)

func parseAgoraSEI(nalUnit: Data) -> AgoraSEI? {
    var pos = 0
    
    // ① NAL header
    guard nalUnit[pos] == 0x06 else { return nil }  // SEI NAL?
    pos += 1
    
    // ② payload_type (0xFF accumulation)
    var payloadType = 0
    while nalUnit[pos] == 0xFF {
        payloadType += 255
        pos += 1
    }
    payloadType += Int(nalUnit[pos])
    pos += 1
    
    guard payloadType == 100 else { return nil }  // Agora 커스텀
    
    // ③ payload_size (0xFF accumulation)
    var payloadSize = 0
    while nalUnit[pos] == 0xFF {
        payloadSize += 255
        pos += 1
    }
    payloadSize += Int(nalUnit[pos])
    pos += 1
    
    // ④ payload (JSON)
    let payload = nalUnit.subdata(in: pos..<(pos + payloadSize))
    
    // ⑤ JSON 파싱
    return try? JSONDecoder().decode(AgoraSEI.self, from: payload)
}

struct AgoraSEI: Codable {
    let canvas: Canvas
    let regions: [Region]
    let ver: String
    let ts: Int64
    let app_data: String?
}

struct Canvas: Codable {
    let w: Int
    let h: Int
    let bgnd: String
}

struct Region: Codable {
    let uid: Int
    let x: Int
    let y: Int
    let w: Int
    let h: Int
    let alpha: Float
    let zorder: Int
    let volume: Int
}

def strip_emulation_prevention(buf):
    out = bytearray()
    i = 0
    while i < len(buf):
        if i + 2 < len(buf) and buf[i] == 0x00 and buf[i+1] == 0x00 and buf[i+2] == 0x03:
            out.append(0x00)
            out.append(0x00)
            i += 3
        else:
            out.append(buf[i])
            i += 1
    return bytes(out)

시청자 화면(합성된 1920x1080):
┌─────────────────────────────────────┐
│  [호스트 A: uid=1001]               │
│  (0,0) ~ (960,540)                  │
│ ┌──────────┐                        │
│ │ A 화면   │ [호스트 B: uid=1002]   │
│ └──────────┘ (960,0) ~ (1920,540)   │
│                                     │
│  [호스트 C: uid=1003]               │
│  (0,540) ~ (1920,1080)              │
└─────────────────────────────────────┘

시청자가 좌측 상단을 탭 → SEI의 regions 배열 탐색 →
matching region.uid = 1001 → "호스트 A 클릭" 이벤트 발화

□ 1. 송출 시나리오가 Agora Media Push인지 확인 (RTC 원본은 SEI 없음)
□ 2. 트랜스코딩 옵션이 활성화되어 있는지 (raw passthrough면 SEI 없음)
□ 3. 시청자 측 파서가 AVCC vs Annex B 포맷을 정확히 이해
□ 4. NAL header 0x06 → SEI 식별
□ 5. payload_type 100 (0x64) 확인 후 Agora SEI로 분기
□ 6. 0xFF 누적 길이 인코딩 정확히 처리
□ 7. emulation_prevention_byte (00 00 03) 제거
□ 8. JSON 파싱 후 canvas / regions / app_data 활용
□ 9. SEI 미수신 시 폴백 동작 정의 (이전 값 유지 or 기본 레이아웃)
□ 10. (옵션) RTM/WebSocket으로 업링크 채널 별도 구축

┌──────────────────────────────────────────────────────┐
│  Agora Media Push                                    │
│       │                                              │
│       ▼ (자동)                                       │
│  H.264 NAL 스트림에 SEI 삽입                         │
│       │                                              │
│       ▼                                              │
│  [06 64 bd ... JSON ...]                             │
│   │   │  │  └─ canvas, regions, app_data, ts, ver   │
│   │   │  └──── payload_size (0xFF 누적)             │
│   │   └─────── payload_type 100 (Agora 커스텀)      │
│   └─────────── NAL type 6 (SEI)                     │
│       │                                              │
│       ▼                                              │
│  RTMP/AVCC 또는 RTSP/Annex B로 송출                  │
│       │                                              │
│       ▼                                              │
│  시청자 클라이언트 파서                               │
│  ① NAL 디먹스 → ② SEI 식별 → ③ 길이 파싱            │
│  ④ emulation_prevention 제거 → ⑤ JSON 파싱          │
│       │                                              │
│       ▼                                              │
│  UI 활용 (클릭 영역, 자막 큐, 광고 트리거 등)        │
└──────────────────────────────────────────────────────┘