fix(hls): keyframe-gated VOD segment cut so the IRAP opens its segment (#92)

Root cause (confirmed via segverify vs ffmpeg ground truth): VOD routed each
packet to a segment by its DTS against PTS-valued plan boundaries. Under
B-frame reorder a keyframe's DTS is below its PTS, so the boundary IRAP fell
into the previous segment and the next segment started mid-GOP, decode-
dependent on its predecessor. AVPlayer hitting a fresh decode at such a
boundary (rebuffer recovery) showed transient blocky corruption (the #92
report on native DV P8.1). The defect was general to reordered content, not
just open-GOP CRA: closed-GOP-with-B-frames was equally affected.

Fix: VODSegmentCutter cuts in decode order, keyframe-gated, like the existing
live path and like FFmpeg's hls muxer. A segment opens at the IRAP that
reaches its plan boundary, so the IRAP is the segment's first sample and its
open-GOP RASL leading pictures (which follow in decode order) stay with it; a
fresh decode then starts cleanly at the IRAP and discards RASL via
NoRaslOutputFlag. Audio routing is unchanged (still presentation-aligned by
PTS, as FFmpeg does). EXTINF still derives from the plan boundaries.

Verified locally with `aetherctl segverify` on synthetic HEVC: before, 1/8
segments independently decodable (only seg0); after, 8/8 for BOTH open-GOP
and closed-GOP, matching ffmpeg's own hls segmenter. 9 TDD tests for the
cutter (RASL-stays-with-keyframe, intra-segment keyframe does not cut, base-
index restart, sparse jump, end-boundary clamp). The #92 witness verdict now
keys off "starts at IRAP" (trailing RASL are legitimate). Full suite green
(XCTest 236, Swift Testing 268), strict-concurrency 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/HLSSegmentProducer.swift

@@ -245,6 +245,9 @@ final class HLSSegmentProducer: @unchecked Sendable {
     private var pendingVideoSegIndex: Int = 0
     private var pendingAudioSegIndex: Int = 0
 
+    /// VOD keyframe-gated cutter: opens each segment at the IRAP that reaches its plan boundary (#92).
+    private var vodCutter: VODSegmentCutter
+
     private var loggedFirstVideoPktInfo = false
     private var loggedP7ConversionFailure = false
     /// Latched false at SSAI program switch (ad creatives are H.264; mirrors muxer's isReinit ? false : videoConfig.convertP7ToProfile81).
@@ -313,14 +316,17 @@ final class HLSSegmentProducer: @unchecked Sendable {
         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 {
+        // A segment is independently decodable iff its FIRST sample is an IRAP. Open-GOP RASL that follow
+        // the IRAP in the same segment are fine (a fresh decode discards them via NoRaslOutputFlag); only
+        // a segment that starts on a non-IRAP (the pre-fix mid-GOP cut) is dependent on its predecessor.
+        let startsAtIRAP = HEVCAccessUnitProbe.isIRAP(dbg92CurKfType)
+        if !startsAtIRAP { dbg92NonIndependentSegs += 1 }
+        if dbg92SegsSeen <= 5 || !startsAtIRAP {
             EngineLog.emit(
                 "[HLSSegmentProducer] #92 seg-\(dbg92CurSeg) "
                 + "keyframe=\(HEVCAccessUnitProbe.label(forSliceType: dbg92CurKfType)) "
                 + "frames=\(dbg92FramesInSeg) leadingRASL=\(dbg92LeadingInSeg) "
-                + "independent=\(nonIndependent ? "NO" : "yes")",
+                + "independent=\(startsAtIRAP ? "yes" : "NO")",
                 category: .session
             )
         }
@@ -589,6 +595,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
         self.sourceVideoTimeBase = video.timeBase
         self.targetSegmentDurationSeconds = targetSegmentDurationSeconds
         self.segmentBoundaries = segmentBoundaries
+        self.vodCutter = VODSegmentCutter(boundaries: segmentBoundaries, baseIndex: baseIndex)
         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
@@ -1937,17 +1944,16 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         }
                     }
                     // Live: keyframe cutter uses shifted pts. VOD: unused; routing uses prev.dts at look-behind site.
+                    let isVideoKeyframe = (packet.pointee.flags & AV_PKT_FLAG_KEY) != 0
+                    // VOD now cuts keyframe-gated like live (and like FFmpeg's hls muxer): a segment opens
+                    // at the IRAP that reaches its plan boundary, so the IRAP is the segment's first sample
+                    // and its open-GOP RASL leading pictures stay with it (#92). Routing by DTS against PTS
+                    // boundaries used to drop the IRAP (dts < pts) into the previous segment.
                     let thisVideoSeg = isLive
-                        ? liveVideoSegmentIndex(
-                            pts: packet.pointee.pts,
-                            isKeyframe: (packet.pointee.flags & AV_PKT_FLAG_KEY) != 0
-                          )
-                        : 0
+                        ? liveVideoSegmentIndex(pts: packet.pointee.pts, isKeyframe: isVideoKeyframe)
+                        : vodCutter.index(pts: packet.pointee.pts, isKeyframe: isVideoKeyframe)
                     if let prev = pendingVideoPkt {
-                        // VOD: use DTS (not PTS) because HEVC open-GOP CRA leading B-frames have PTS in the previous segment.
-                        let prevSeg = isLive
-                            ? pendingVideoSegIndex
-                            : segmentIndex(forSourcePts: prev.pointee.dts)
+                        let prevSeg = pendingVideoSegIndex
                         // #65 ledger: at each VOD segment open, map the segment's item-axis start (what AVPlayer and
                         // currentTime see) to the TRUE source content muxed there. drift = actual source - planned
                         // source for this index; non-zero means the presented frame leads the clock (Root B positively
@@ -2010,7 +2016,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
                         }
                     }
                     pendingVideoPkt = packet
-                    if isLive { pendingVideoSegIndex = thisVideoSeg }
+                    pendingVideoSegIndex = thisVideoSeg   // live: liveVideoSegmentIndex; VOD: keyframe-gated cutter
                     pktPtr = nil  // ownership transferred to pendingVideoPkt
                     continue
                 }
@@ -2129,9 +2135,7 @@ final class HLSSegmentProducer: @unchecked Sendable {
 
         // Flush look-behind; fallback duration produces tail-correct trun for the final fragment.
         if let prev = pendingVideoPkt {
-            let prevSeg = isLive
-                ? pendingVideoSegIndex
-                : segmentIndex(forSourcePts: prev.pointee.dts)
+            let prevSeg = pendingVideoSegIndex   // unified: live + VOD both carry the routed index
             if let muxer = ensureMuxer(forSegmentIndex: prevSeg) {
                 finalizeAndWriteVideo(prev, nextDts: nil, muxer: muxer)
                 bumpPacketsWritten()

Sources/AetherEngine/Video/VODSegmentCutter.swift

@@ -0,0 +1,43 @@
+import Foundation
+
+/// Decode-order, keyframe-gated VOD segment cutter.
+///
+/// A new segment opens only when a keyframe whose presentation time reaches the next plan boundary
+/// arrives, so the IRAP becomes that segment's first sample and its open-GOP RASL leading pictures
+/// (which follow it in decode order) stay with it. This matches how FFmpeg's hls muxer and Apple's
+/// tools cut, and makes every segment start on a clean random-access point.
+///
+/// It replaces routing each packet by its DTS against PTS-valued boundaries: under B-frame reorder a
+/// keyframe's DTS is below its PTS, so `dts < boundary[N]` dropped the keyframe into segment N-1 and
+/// left segment N starting mid-GOP, decode-dependent on its predecessor (#92). Both open-GOP (CRA +
+/// RASL) and closed-GOP-with-B-frames were affected because the reorder delay is constant across the
+/// stream. The cut point is the only thing that changes; EXTINF still comes from the plan boundaries.
+struct VODSegmentCutter {
+
+    /// Plan boundaries in source PTS: `boundaries[i]` is the start PTS of segment `baseIndex + i`.
+    /// `boundaries.count` is the segment count + 1 (the last entry is the end of the final segment).
+    let boundaries: [Int64]
+    let baseIndex: Int
+    private(set) var current: Int
+
+    init(boundaries: [Int64], baseIndex: Int) {
+        self.boundaries = boundaries
+        self.baseIndex = baseIndex
+        self.current = baseIndex
+    }
+
+    /// Segment index for a video packet, in decode order. Advances on a keyframe that has reached the
+    /// next boundary; every other packet (and an intra-segment keyframe that has not yet reached the
+    /// next boundary, e.g. when the GOP is shorter than the segment) stays in the current segment.
+    mutating func index(pts: Int64, isKeyframe: Bool) -> Int {
+        guard isKeyframe, pts != Int64.min else { return current }
+        // boundaries[count-1] is the end of the final segment, not a segment start, so the last segment
+        // a keyframe can open is local (count-2): advance only while the next entry is a real start.
+        var nextLocal = (current - baseIndex) + 1
+        while nextLocal < boundaries.count - 1, pts >= boundaries[nextLocal] {
+            current += 1
+            nextLocal += 1
+        }
+        return current
+    }
+}

Tests/AetherEngineTests/VODSegmentCutterTests.swift

@@ -0,0 +1,77 @@
+import XCTest
+@testable import AetherEngine
+
+final class VODSegmentCutterTests: XCTestCase {
+
+    // 4 segments of 4s each, boundaries in ms (source TB 1/1000): starts 0,4,8,12 + end 16.
+    private let fourSeg: [Int64] = [0, 4000, 8000, 12000, 16000]
+
+    func testFirstKeyframeOpensBaseSegment() {
+        var c = VODSegmentCutter(boundaries: fourSeg, baseIndex: 0)
+        XCTAssertEqual(c.index(pts: 0, isKeyframe: true), 0)   // first IRAP stays in seg 0
+    }
+
+    func testNonKeyframesStayInCurrentSegment() {
+        var c = VODSegmentCutter(boundaries: fourSeg, baseIndex: 0)
+        _ = c.index(pts: 0, isKeyframe: true)
+        XCTAssertEqual(c.index(pts: 1000, isKeyframe: false), 0)
+        XCTAssertEqual(c.index(pts: 2000, isKeyframe: false), 0)
+    }
+
+    func testBoundaryKeyframeOpensNextSegment() {
+        var c = VODSegmentCutter(boundaries: fourSeg, baseIndex: 0)
+        _ = c.index(pts: 0, isKeyframe: true)
+        XCTAssertEqual(c.index(pts: 4000, isKeyframe: true), 1)   // IRAP at 4s opens seg 1
+        XCTAssertEqual(c.index(pts: 8000, isKeyframe: true), 2)
+        XCTAssertEqual(c.index(pts: 12000, isKeyframe: true), 3)
+    }
+
+    /// The #92 fix: open-GOP RASL leading pictures arrive in decode order AFTER the CRA but carry a PTS
+    /// BEFORE it. They must stay in the CRA's segment, not be re-routed to the previous one.
+    func testRaslLeadingPicturesStayWithTheirKeyframe() {
+        var c = VODSegmentCutter(boundaries: fourSeg, baseIndex: 0)
+        _ = c.index(pts: 0, isKeyframe: true)
+        XCTAssertEqual(c.index(pts: 4000, isKeyframe: true), 1)    // CRA opens seg 1
+        XCTAssertEqual(c.index(pts: 3958, isKeyframe: false), 1)   // RASL, pts < CRA -> stays in seg 1
+        XCTAssertEqual(c.index(pts: 3917, isKeyframe: false), 1)
+        XCTAssertEqual(c.index(pts: 4083, isKeyframe: false), 1)   // trailing -> seg 1
+    }
+
+    /// GOP shorter than the segment: an intra-segment keyframe that has not reached the next boundary
+    /// must NOT open a new segment.
+    func testIntraSegmentKeyframeDoesNotCut() {
+        let twoSeg: [Int64] = [0, 8000, 16000]   // 8s segments
+        var c = VODSegmentCutter(boundaries: twoSeg, baseIndex: 0)
+        _ = c.index(pts: 0, isKeyframe: true)
+        XCTAssertEqual(c.index(pts: 4000, isKeyframe: true), 0)   // mid-segment IRAP stays in seg 0
+        XCTAssertEqual(c.index(pts: 8000, isKeyframe: true), 1)   // boundary IRAP opens seg 1
+    }
+
+    func testBaseIndexOffsetForRestart() {
+        let b: [Int64] = [264_000, 268_000, 272_000, 276_000]   // 3 segments: 264, 265, 266
+        var c = VODSegmentCutter(boundaries: b, baseIndex: 264)
+        XCTAssertEqual(c.index(pts: 264_000, isKeyframe: true), 264)
+        XCTAssertEqual(c.index(pts: 268_000, isKeyframe: true), 265)
+        XCTAssertEqual(c.index(pts: 272_000, isKeyframe: true), 266)
+    }
+
+    func testSparseKeyframeJumpAdvancesMultiple() {
+        var c = VODSegmentCutter(boundaries: fourSeg, baseIndex: 0)
+        _ = c.index(pts: 0, isKeyframe: true)
+        XCTAssertEqual(c.index(pts: 12000, isKeyframe: true), 3)   // skips 1,2 in one step
+    }
+
+    func testNeverAdvancesPastLastSegment() {
+        var c = VODSegmentCutter(boundaries: fourSeg, baseIndex: 0)
+        _ = c.index(pts: 0, isKeyframe: true)
+        // Keyframes well past the final boundary clamp at the last segment (count-1 boundaries => seg 3).
+        XCTAssertEqual(c.index(pts: 99_000, isKeyframe: true), 3)
+        XCTAssertEqual(c.index(pts: 99_000, isKeyframe: true), 3)
+    }
+
+    func testNoptsKeyframeStaysPut() {
+        var c = VODSegmentCutter(boundaries: fourSeg, baseIndex: 0)
+        _ = c.index(pts: 0, isKeyframe: true)
+        XCTAssertEqual(c.index(pts: Int64.min, isKeyframe: true), 0)
+    }
+}