diag(player): per-segment open-GOP witness for #92

Native DV Profile 8.1 HEVC shows transient blocky glitches on the
loopback-HLS path, intermittent and varying per play, absent in
direct-decode players, while P7 (same dvvC+db1p signaling) is clean.
That signature points at non-independently-decodable segments rather
than any static byte/signaling difference.

The producer already drops HEVC RASL leading B-frames at the initial
keyframe gate (open-GOP CRA), but mid-stream it routes by DTS and keeps
each CRA together with its RASL leading pictures, whose PTS lands in the
previous GOP. Those segments reference the prior segment and are not
independently decodable; a fresh decode at such a boundary (rebuffer
recovery) shows blocky corruption until the next clean keyframe.

This adds a pure-logging witness (no behaviour change) to confirm the
hypothesis on a real asset:
- HEVCAccessUnitProbe: read-only AVCC NAL walk classifying a keyframe
  access unit as IDR vs CRA vs BLA and recognizing RASL/RADL slices.
- HLSSegmentProducer (VOD + HEVC only): per-segment log of keyframe
  type, frame count, count of leading RASL pictures whose PTS precedes
  the segment keyframe, and an independent/NO verdict, plus a rolling
  aggregate.

8 unit tests for the probe. Full suite green (XCTest 220, Swift Testing
268), strict-concurrency build clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XZTEfmztPE8hAdjHdBr9BH

Author: superuser404notfound

Sources/AetherEngine/Video/HEVCAccessUnitProbe.swift

@@ -0,0 +1,64 @@
+import Foundation
+
+/// Read-only probe over an HEVC access unit in AVCC layout (length-prefixed NAL units).
+/// Used by the #92 open-GOP diagnostics: classify a segment's leading keyframe as IDR vs CRA vs
+/// BLA and recognize RASL/RADL leading-picture slice types. NAL-header inspection only, no slice
+/// parse, no allocation. AVCC layout matches DoviRpuConverter (4-byte big-endian length prefix).
+enum HEVCAccessUnitProbe {
+
+    // HEVC NAL unit types (H.265 Table 7-1), the subset we classify.
+    static let nalRaslN: UInt8 = 8     // RASL_N: leading, dropped when NoRaslOutputFlag is set
+    static let nalRaslR: UInt8 = 9     // RASL_R
+    static let nalRadlN: UInt8 = 6
+    static let nalRadlR: UInt8 = 7
+    static let nalBlaWLp: UInt8 = 16
+    static let nalIdrWRadl: UInt8 = 19
+    static let nalIdrNLp: UInt8 = 20
+    static let nalCra: UInt8 = 21
+
+    /// VCL NAL types are 0...31; non-VCL (VPS/SPS/PPS/SEI/AUD) are 32...63.
+    static func isVCL(_ t: UInt8) -> Bool { t <= 31 }
+    /// IRAP (random-access point) slice types: BLA 16...18, IDR 19...20, CRA 21 (16...23 inclusive).
+    static func isIRAP(_ t: UInt8) -> Bool { t >= 16 && t <= 23 }
+    static func isIDR(_ t: UInt8) -> Bool { t == 19 || t == 20 }
+    static func isCRA(_ t: UInt8) -> Bool { t == 21 }
+    static func isRASL(_ t: UInt8) -> Bool { t == 8 || t == 9 }
+
+    /// First VCL slice NAL type in the access unit, skipping non-VCL NALs (VPS/SPS/PPS/SEI/AUD).
+    /// Returns nil when there is no VCL NAL or the buffer is malformed/truncated.
+    static func firstSliceNALType(
+        _ data: UnsafePointer<UInt8>, size: Int, lengthPrefixSize: Int = 4
+    ) -> UInt8? {
+        var off = 0
+        while off + lengthPrefixSize <= size {
+            var len = 0
+            for i in 0..<lengthPrefixSize { len = (len << 8) | Int(data[off + i]) }
+            let nalStart = off + lengthPrefixSize
+            if len <= 0 || nalStart + len > size { break }
+            // HEVC NAL header byte0: forbidden_zero(1) | nal_unit_type(6) | nuh_layer_id MSB(1).
+            let t = (data[nalStart] >> 1) & 0x3F
+            if isVCL(t) { return t }
+            off = nalStart + len
+        }
+        return nil
+    }
+
+    static func firstSliceNALType(_ bytes: [UInt8], lengthPrefixSize: Int = 4) -> UInt8? {
+        bytes.withUnsafeBufferPointer { buf in
+            guard let base = buf.baseAddress else { return nil }
+            return firstSliceNALType(base, size: buf.count, lengthPrefixSize: lengthPrefixSize)
+        }
+    }
+
+    /// Short label for diagnostics.
+    static func label(forSliceType t: UInt8) -> String {
+        switch t {
+        case 19, 20: return "IDR"
+        case 21: return "CRA"
+        case 16, 17, 18: return "BLA"
+        case 8, 9: return "RASL"
+        case 6, 7: return "RADL"
+        default: return isVCL(t) ? "TRAIL(\(t))" : "nonVCL(\(t))"
+        }
+    }
+}

Sources/AetherEngine/Video/HLSSegmentProducer.swift

@@ -291,6 +291,49 @@ final class HLSSegmentProducer: @unchecked Sendable {
     private var firstActualVideoPts: Int64 = Int64.min
     private var loggedFirstLeadingDrop: Bool = false
 
+    // #92 diagnostics (VOD, HEVC): per-segment open-GOP witness. Confirms whether mid-stream segment
+    // keyframes are CRA (open-GOP) vs IDR, and whether segments carry RASL leading pictures whose PTS
+    // precedes their own keyframe (making the segment non-independent). Pure logging, no behaviour change.
+    private var dbg92Enabled: Bool = false
+    private var dbg92CurSeg: Int = Int.min
+    private var dbg92CurKfType: UInt8 = 0xFF
+    private var dbg92SegKfPts: Int64 = Int64.min
+    private var dbg92LeadingInSeg: Int = 0
+    private var dbg92FramesInSeg: Int = 0
+    private var dbg92IdrSegs: Int = 0
+    private var dbg92CraSegs: Int = 0
+    private var dbg92NonIndependentSegs: Int = 0
+    private var dbg92SegsSeen: Int = 0
+
+    /// #92: flush the accumulated open-GOP witness for the segment that just ended. Logs every
+    /// non-independent segment (CRA keyframe carrying RASL leading pictures, the smoking gun) plus the
+    /// first few segments verbatim, and a rolling aggregate every 50 segments to bound log volume.
+    private func emitDbg92SegmentSummary() {
+        guard dbg92Enabled, dbg92CurSeg != Int.min else { return }
+        dbg92SegsSeen += 1
+        if HEVCAccessUnitProbe.isIDR(dbg92CurKfType) { dbg92IdrSegs += 1 }
+        if HEVCAccessUnitProbe.isCRA(dbg92CurKfType) { dbg92CraSegs += 1 }
+        let nonIndependent = dbg92LeadingInSeg > 0
+        if nonIndependent { dbg92NonIndependentSegs += 1 }
+        if dbg92SegsSeen <= 5 || nonIndependent {
+            EngineLog.emit(
+                "[HLSSegmentProducer] #92 seg-\(dbg92CurSeg) "
+                + "keyframe=\(HEVCAccessUnitProbe.label(forSliceType: dbg92CurKfType)) "
+                + "frames=\(dbg92FramesInSeg) leadingRASL=\(dbg92LeadingInSeg) "
+                + "independent=\(nonIndependent ? "NO" : "yes")",
+                category: .session
+            )
+        }
+        if dbg92SegsSeen % 50 == 0 {
+            EngineLog.emit(
+                "[HLSSegmentProducer] #92 aggregate: segs=\(dbg92SegsSeen) "
+                + "IDR=\(dbg92IdrSegs) CRA=\(dbg92CraSegs) "
+                + "nonIndependent=\(dbg92NonIndependentSegs)",
+                category: .session
+            )
+        }
+    }
+
     /// Pre-gate drop counters; surface the "lädt unendlich" failure mode when the gate never opens.
     private var pregateVideoDropCount: Int = 0
     private var pregateWaitStart: Date?
@@ -547,6 +590,8 @@ final class HLSSegmentProducer: @unchecked Sendable {
         self.targetSegmentDurationSeconds = targetSegmentDurationSeconds
         self.segmentBoundaries = segmentBoundaries
         self.isLive = isLive
+        // #92: open-GOP witness only matters for the VOD keyframe-plan path on HEVC sources.
+        self.dbg92Enabled = !isLive && video.codecpar.pointee.codec_id == AV_CODEC_ID_HEVC
         self.liveCurrentSegmentIndex = baseIndex
         self.videoFallbackDurationPts = videoFallbackDurationPts
         self.audioFallbackDurationPts = audioFallbackDurationPts
@@ -1930,6 +1975,29 @@ final class HLSSegmentProducer: @unchecked Sendable {
                                 category: .session
                             )
                         }
+                        // #92: per-segment open-GOP witness. The first packet routed to a new VOD segment
+                        // is that segment's boundary keyframe (kf.dts == kf.pts == plan boundary). Frames in
+                        // the segment whose PTS precedes the keyframe PTS are RASL leading pictures referencing
+                        // the previous GOP -> the segment is not independently decodable (see #92 analysis).
+                        if dbg92Enabled {
+                            if prevSeg != dbg92CurSeg {
+                                emitDbg92SegmentSummary()
+                                dbg92CurSeg = prevSeg
+                                dbg92SegKfPts = prev.pointee.pts
+                                dbg92FramesInSeg = 0
+                                dbg92LeadingInSeg = 0
+                                dbg92CurKfType = 0xFF
+                                if let data = prev.pointee.data, prev.pointee.size > 0 {
+                                    dbg92CurKfType = HEVCAccessUnitProbe.firstSliceNALType(
+                                        data, size: Int(prev.pointee.size)) ?? 0xFF
+                                }
+                            }
+                            dbg92FramesInSeg += 1
+                            if dbg92SegKfPts != Int64.min, prev.pointee.pts != Int64.min,
+                               prev.pointee.pts < dbg92SegKfPts {
+                                dbg92LeadingInSeg += 1
+                            }
+                        }
                         if let muxer = ensureMuxer(forSegmentIndex: prevSeg) {
                             finalizeAndWriteVideo(prev, nextDts: packet.pointee.dts, muxer: muxer)
                             bumpPacketsWritten()

Tests/AetherEngineTests/HEVCAccessUnitProbeTests.swift

@@ -0,0 +1,72 @@
+import XCTest
+@testable import AetherEngine
+
+final class HEVCAccessUnitProbeTests: XCTestCase {
+
+    /// Build one AVCC NAL (4-byte BE length prefix + 2-byte HEVC header + payload).
+    private func nal(_ type: UInt8, payload: [UInt8] = [0x00]) -> [UInt8] {
+        // byte0: forbidden_zero(0) | nal_unit_type(6) | nuh_layer_id MSB(0) = type << 1.
+        let header: [UInt8] = [(type << 1) & 0x7E, 0x01]
+        let body = header + payload
+        let n = body.count
+        let prefix: [UInt8] = [
+            UInt8((n >> 24) & 0xFF), UInt8((n >> 16) & 0xFF),
+            UInt8((n >> 8) & 0xFF), UInt8(n & 0xFF),
+        ]
+        return prefix + body
+    }
+
+    func testIDRAccessUnitWithParameterSets() {
+        let au = nal(32) + nal(33) + nal(34) + nal(19)  // VPS, SPS, PPS, IDR_W_RADL
+        let t = HEVCAccessUnitProbe.firstSliceNALType(au)
+        XCTAssertEqual(t, 19)
+        XCTAssertTrue(HEVCAccessUnitProbe.isIDR(t!))
+        XCTAssertTrue(HEVCAccessUnitProbe.isIRAP(t!))
+        XCTAssertFalse(HEVCAccessUnitProbe.isCRA(t!))
+    }
+
+    func testCRAAccessUnitSkipsLeadingSEI() {
+        let au = nal(39) + nal(21)  // SEI_PREFIX (non-VCL), CRA_NUT
+        let t = HEVCAccessUnitProbe.firstSliceNALType(au)
+        XCTAssertEqual(t, 21)
+        XCTAssertTrue(HEVCAccessUnitProbe.isCRA(t!))
+        XCTAssertTrue(HEVCAccessUnitProbe.isIRAP(t!))
+        XCTAssertFalse(HEVCAccessUnitProbe.isIDR(t!))
+    }
+
+    func testRASLLeadingPictureIsNotIRAP() {
+        let t = HEVCAccessUnitProbe.firstSliceNALType(nal(9))  // RASL_R
+        XCTAssertEqual(t, 9)
+        XCTAssertTrue(HEVCAccessUnitProbe.isRASL(t!))
+        XCTAssertFalse(HEVCAccessUnitProbe.isIRAP(t!))
+    }
+
+    func testTrailingPictureIsNotIRAP() {
+        let t = HEVCAccessUnitProbe.firstSliceNALType(nal(1))  // TRAIL_R
+        XCTAssertEqual(t, 1)
+        XCTAssertFalse(HEVCAccessUnitProbe.isIRAP(t!))
+        XCTAssertFalse(HEVCAccessUnitProbe.isRASL(t!))
+    }
+
+    func testNonVCLOnlyReturnsNil() {
+        let au = nal(32) + nal(33) + nal(34)  // VPS, SPS, PPS only
+        XCTAssertNil(HEVCAccessUnitProbe.firstSliceNALType(au))
+    }
+
+    func testTruncatedPrefixReturnsNil() {
+        XCTAssertNil(HEVCAccessUnitProbe.firstSliceNALType([0x00, 0x00, 0x10]))
+    }
+
+    func testLengthExceedingBufferStops() {
+        // prefix claims 100 bytes; buffer holds 2 -> stop, nil.
+        XCTAssertNil(HEVCAccessUnitProbe.firstSliceNALType([0x00, 0x00, 0x00, 0x64, 0x26, 0x01]))
+    }
+
+    func testLabels() {
+        XCTAssertEqual(HEVCAccessUnitProbe.label(forSliceType: 21), "CRA")
+        XCTAssertEqual(HEVCAccessUnitProbe.label(forSliceType: 19), "IDR")
+        XCTAssertEqual(HEVCAccessUnitProbe.label(forSliceType: 20), "IDR")
+        XCTAssertEqual(HEVCAccessUnitProbe.label(forSliceType: 9), "RASL")
+        XCTAssertEqual(HEVCAccessUnitProbe.label(forSliceType: 7), "RADL")
+    }
+}