@blockcast/mmt-container 0.1.0-main.ce3c8aeb7f68 → 0.1.0-main.cf0df54ddcf4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/README.md +44 -3
  2. package/dist/block-policy.d.ts +314 -0
  3. package/dist/block-policy.d.ts.map +1 -0
  4. package/dist/block-policy.js +466 -0
  5. package/dist/block-policy.js.map +7 -0
  6. package/dist/browser-runtime.js +2796 -573
  7. package/dist/browser-runtime.js.map +4 -4
  8. package/dist/catalog-fec-params.d.ts +28 -4
  9. package/dist/catalog-fec-params.d.ts.map +1 -1
  10. package/dist/catalog-fec-params.js +28 -1
  11. package/dist/catalog-fec-params.js.map +3 -3
  12. package/dist/cmaf-block-assembler.d.ts +25 -11
  13. package/dist/cmaf-block-assembler.d.ts.map +1 -1
  14. package/dist/cmaf-block-assembler.js +76 -177
  15. package/dist/cmaf-block-assembler.js.map +3 -3
  16. package/dist/cmaf-group-batcher.js.map +1 -1
  17. package/dist/cmcd-producer.d.ts.map +1 -1
  18. package/dist/cmcd-producer.js +0 -3
  19. package/dist/cmcd-producer.js.map +2 -2
  20. package/dist/conceal-timeline.d.ts +123 -0
  21. package/dist/conceal-timeline.d.ts.map +1 -0
  22. package/dist/conceal-timeline.js +122 -0
  23. package/dist/conceal-timeline.js.map +7 -0
  24. package/dist/duplicate-ledger.d.ts +197 -0
  25. package/dist/duplicate-ledger.d.ts.map +1 -0
  26. package/dist/duplicate-ledger.js +226 -0
  27. package/dist/duplicate-ledger.js.map +7 -0
  28. package/dist/fec-manager.d.ts +113 -23
  29. package/dist/fec-manager.d.ts.map +1 -1
  30. package/dist/fec-manager.js +879 -131
  31. package/dist/fec-manager.js.map +4 -4
  32. package/dist/fec-worker-setup.js +0 -8
  33. package/dist/fec-worker-setup.js.map +2 -2
  34. package/dist/index.d.ts +7 -5
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +27 -3
  37. package/dist/index.js.map +2 -2
  38. package/dist/media-router.d.ts +5 -2
  39. package/dist/media-router.d.ts.map +1 -1
  40. package/dist/media-router.js +13 -1
  41. package/dist/media-router.js.map +2 -2
  42. package/dist/mmtp-container-parser.d.ts +85 -0
  43. package/dist/mmtp-container-parser.d.ts.map +1 -1
  44. package/dist/mmtp-container-parser.js +271 -4
  45. package/dist/mmtp-container-parser.js.map +2 -2
  46. package/dist/mmtp-container-parser.no-modules.js +273 -5
  47. package/dist/mmtp-container-parser.no-modules.js.map +3 -3
  48. package/dist/mmtp-decode-pipeline.d.ts +7 -1
  49. package/dist/mmtp-decode-pipeline.d.ts.map +1 -1
  50. package/dist/mmtp-decode-pipeline.js +279 -8
  51. package/dist/mmtp-decode-pipeline.js.map +2 -2
  52. package/dist/mmtp-router.d.ts +88 -12
  53. package/dist/mmtp-router.d.ts.map +1 -1
  54. package/dist/mmtp-router.js +1031 -247
  55. package/dist/mmtp-router.js.map +3 -3
  56. package/dist/mmtp-to-cmaf.d.ts +0 -12
  57. package/dist/mmtp-to-cmaf.d.ts.map +1 -1
  58. package/dist/mmtp-to-cmaf.js +0 -62
  59. package/dist/mmtp-to-cmaf.js.map +2 -2
  60. package/dist/multicast-manager.d.ts +148 -16
  61. package/dist/multicast-manager.d.ts.map +1 -1
  62. package/dist/multicast-manager.js +2445 -477
  63. package/dist/multicast-manager.js.map +4 -4
  64. package/dist/multicast-transport.d.ts.map +1 -1
  65. package/dist/multicast-transport.js +119 -22
  66. package/dist/multicast-transport.js.map +3 -3
  67. package/dist/no-modules.js +271 -4
  68. package/dist/no-modules.js.map +2 -2
  69. package/dist/repair-fetch.d.ts +172 -23
  70. package/dist/repair-fetch.d.ts.map +1 -1
  71. package/dist/repair-fetch.js +235 -85
  72. package/dist/repair-fetch.js.map +4 -4
  73. package/dist/wasm-mmtp-container-parser.js +271 -4
  74. package/dist/wasm-mmtp-container-parser.js.map +2 -2
  75. package/node_modules/@blockcast/fec-worker/README.md +4 -4
  76. package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.d.ts +0 -2
  77. package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.d.ts.map +1 -1
  78. package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.js +0 -8
  79. package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.js.map +1 -1
  80. package/node_modules/@blockcast/fec-worker/dist/fec-worker-types.d.ts +1 -7
  81. package/node_modules/@blockcast/fec-worker/dist/fec-worker-types.d.ts.map +1 -1
  82. package/node_modules/@blockcast/fec-worker/dist/fec-worker.js +4 -33
  83. package/node_modules/@blockcast/fec-worker/dist/fec-worker.js.map +2 -2
  84. package/node_modules/@blockcast/fec-worker/src/fec-worker-client.ts +0 -9
  85. package/node_modules/@blockcast/fec-worker/src/fec-worker-types.ts +1 -4
  86. package/node_modules/@blockcast/fec-worker/src/fec-worker.ts +15 -51
  87. package/package.json +14 -6
  88. package/schemas/catalog.schema.json +5 -0
  89. package/src/block-policy.ts +903 -0
  90. package/src/catalog-fec-params.ts +62 -5
  91. package/src/cmaf-block-assembler.ts +60 -151
  92. package/src/cmcd-producer.ts +0 -5
  93. package/src/conceal-timeline.ts +255 -0
  94. package/src/duplicate-ledger.ts +372 -0
  95. package/src/fec-manager.ts +742 -139
  96. package/src/index.ts +53 -1
  97. package/src/media-router.ts +22 -4
  98. package/src/mmtp-container-parser.ts +421 -1
  99. package/src/mmtp-decode-pipeline.ts +23 -6
  100. package/src/mmtp-router.ts +701 -93
  101. package/src/mmtp-to-cmaf.ts +1 -101
  102. package/src/multicast-manager.ts +587 -89
  103. package/src/multicast-transport.ts +108 -19
  104. package/src/repair-fetch.ts +491 -153
package/README.md CHANGED
@@ -65,6 +65,8 @@ The package exposes a wide subpath surface so consumers can tree-shake aggressiv
65
65
  | `./loc` | LOC FEC extension headers (`FecSourceInfo`, `AuthTag`) |
66
66
  | `./codec-utils` | H.264 helpers — Annex-B ↔ AVCC, SPS/PPS extraction, `mmtpTimestampToMicros`, ADTS wrap |
67
67
  | `./fec-manager` | `FECManager` — per-track FEC decoder lifecycle (sync WASM + Worker variants) |
68
+ | `./block-policy` | Keyframe-protected repair policy — `BlockClassifier`, `repairPriorityForClass`, `decideGap` |
69
+ | `./conceal-timeline` | Sink concealment — `videoConcealModeForCodec`, `HoldLastTimeline`, `AudioGapConcealer` |
68
70
  | `./mmtp-router` | `MmtpRouter` — packet routing with two-phase FEC feed |
69
71
  | `./multicast-transport` | `MulticastTransport` — `window.multicast` gateway `subscribe({ consume: 'bytes' })` wrapper |
70
72
  | `./multicast-manager` | `MulticastManager` — backwards-compat facade composing transport + router + FEC |
@@ -82,7 +84,7 @@ The package exposes a wide subpath surface so consumers can tree-shake aggressiv
82
84
  | `./phase14-catalog-override` | Test-harness catalog override hook (`globalThis.__PHASE14_CATALOG_OVERRIDE`) |
83
85
  | `./align` | Group-id derivation (`groupIdForTicks`, `groupIdFor`, `driftCheck`) — shared with Go sender + Rust relay |
84
86
  | `./mmtp-decode-pipeline` | `MmtpDecodePipeline` — unified MoQ + multicast decode path |
85
- | `./mmtp-to-cmaf` | `MmtpToCmaf` + standalone segment builders (`encodeMultiSampleSegment`, `buildVideoInitSegment`, `generateGreenFillNAL`, `generateSilenceFrame`) |
87
+ | `./mmtp-to-cmaf` | `MmtpToCmaf` + standalone segment builders (`encodeMultiSampleSegment`, `buildVideoInitSegment`, `generateSilenceFrame`) |
86
88
  | `./track-pipeline-setup` | `setupTrackPipeline` — shared wiring for both reference players |
87
89
  | `./track-session` | `TrackSession` + `SessionManager` — per-track state machine (Patent Claim 9) |
88
90
 
@@ -263,6 +265,47 @@ class FECManager {
263
265
 
264
266
  `interleaveDepthMs` is the full FEC block span in **milliseconds** per CARP §5.1, valid range 33 ms (interactive / gaming, `MIN_INTERLEAVE_DEPTH_MS`) to 10 000 ms (broadcast ATSC 3.0). `configure()` warns if a positive value below `MIN_INTERLEAVE_DEPTH_MS` (33) is passed — that is almost certainly a raw frame count, not milliseconds — and such sub-floor values never drive the block timeout (the established timeout is preserved instead of collapsing to ~0).
265
267
 
268
+ ### Keyframe-protected repair (`./block-policy`, `./conceal-timeline`)
269
+
270
+ Every FEC block still gets in-band FEC decode. On top of that:
271
+
272
+ - **Classification.** Each block is `keyframe | delta | unknown | audio`, from
273
+ first-arrival network source evidence only (MMTP R bit, MPU number, MFU
274
+ DU-header sample position) against catalog geometry (framerate,
275
+ `interleaveDepthMs`, keyframe interval). Geometry that cannot be derived
276
+ exactly, or any violated invariant, runs the track `all-protected` (every
277
+ video block `unknown`). Vanished blocks are materialised from SBN evidence.
278
+ A frame split across ADJACENT blocks (a K-close) is expected; only source
279
+ packets whose authored order and SBN order disagree (a round-robin
280
+ interleave) trip `block-not-contiguous`. Pass the catalog track name to
281
+ `configureTrackFec(packetId, config, catalogTrackName)` so ABR rungs that
282
+ share a packetId each classify with their own framerate and GOP; a rung on
283
+ such a packetId without its own geometry runs `stream-geometry-absent`.
284
+ - **Repair priority.** `wireRepairFetch` dispatches P0 (`keyframe`/`unknown`)
285
+ and P1 (`audio`) immediately; P2 (`delta`) only while no P0/P1 is queued or
286
+ in flight, earliest deadline first, preempted by any new P0/P1. No timers.
287
+ - **FETCH priority (draft-ramadan-moq-fec §11.4.5).** The transport gets one
288
+ `RepairFetchRequest { repairTrack, sbn, packetId, signal,
289
+ subscriberPriority }` and puts `subscriberPriority` on the FETCH
290
+ (`undefined` = omit the parameter; the publisher then uses 128,
291
+ draft-ietf-moq-transport-16 §9.2.2.3). P0 requests carry
292
+ `min(sourcePriority, 191)`; P1/P2 carry `max(repairPriority, 192)`. Both
293
+ priorities come from `ResolveRepairTarget` (`catalogRepairTarget` reads
294
+ them from a catalog). A missing source priority omits the parameter; a
295
+ missing repair priority declines the delta/audio FETCH; each emits a
296
+ `repair-priority` lifecycle event. Abort MUST send FETCH_CANCEL, from the
297
+ abort handler.
298
+ - **Stall vs conceal.** FEC tracks release frames in authored order; a frame
299
+ after a gap waits until every block that could hold the missing frames
300
+ resolved. When media was lost, the frame carries `gapBefore`
301
+ (`decideGap`): video stalls only when a RAP may be inside the gap; audio
302
+ never stalls. The same object is the manager's `gap` lifecycle event.
303
+ - **Concealment** is hold-last-good-frame (`HoldLastTimeline`) plus exact
304
+ audio sizing (`AudioGapConcealer`). No bitstream is ever synthesised.
305
+
306
+ Typed evidence is `RepairLifecycleEvent` version 2 and
307
+ `MulticastManager.getBlockPolicyStats()`.
308
+
266
309
  This package depends on the FEC primitives from:
267
310
  - **`@blockcast/mmt-fec`** — RaptorQ WASM decoder + OTI codec + `computeFecTimeout`
268
311
  - **`@blockcast/fec-worker`** — Web Worker host, `FecWorkerClient`, `FecTrackStats`
@@ -293,7 +336,6 @@ Standalone helpers exported from the same module:
293
336
  | `encodeMultiSampleSegment(...)` | Multi-sample moof+mdat (one per FEC block — used by `CmafBlockAssembler`) |
294
337
  | `buildVideoInitSegment(avcC, w, h)` | ftyp + moov for AVC |
295
338
  | `buildAudioInitSegment(sampleRate, channels, asc?, timescale?)` | ftyp + moov for AAC / Opus |
296
- | `generateGreenFillNAL(avcC, w, h)` | Green-fill NAL when a FEC block fails (loss visible) |
297
339
  | `generateSilenceFrame(codec, sampleRate, channels)` | Audio silence frame for FEC-failed audio blocks |
298
340
 
299
341
  Per-track timestamp rebase (`#videoBaseTs` / `#audioBaseTs` at `mmtp-to-cmaf.ts:550-562`) prevents the negative-uint64 `tfdt` bug that kills Chromium MediaSource (`CHUNK_DEMUXER_ERROR_APPEND_FAILED`).
@@ -322,7 +364,6 @@ Vendor keys emitted (BLO-1044):
322
364
  | `x-bc-fec-algo` | FEC config | `none` / `raptorq` / `reed-solomon` |
323
365
  | `x-bc-fec-k`, `x-bc-fec-p` | FEC config | source / repair counts |
324
366
  | `x-bc-fec-recovery` | `recoveryRate` | Block-level recovery, 4 decimal places |
325
- | `x-bc-scu` | green-fill count | Omitted when 0 |
326
367
  | `x-bc-alta-verified`, `x-bc-alta-failures` | ALTA stats | Omitted when ALTA disabled (D-09) |
327
368
  | `x-bc-transport` | `TransportSnapshot.transport` | `native` / `amt` / `moq` |
328
369
  | `x-bc-multicast-group`, `x-bc-multicast-source`, `x-bc-amt-relay` | endpoint | Omitted when null |
@@ -0,0 +1,314 @@
1
+ /**
2
+ * Keyframe-protected FEC repair policy.
3
+ *
4
+ * Every FEC block still gets in-band FEC decode. What this module decides is
5
+ * (1) which blocks may hold a keyframe (RAP), so a block short of K at its
6
+ * repair deadline can be repaired over QUIC with the right priority, and
7
+ * (2) what a sink must do with the first frame released after a gap: stall
8
+ * until the next RAP, or conceal and keep playing.
9
+ *
10
+ * The two decisions are deliberately independent. Classification only sets
11
+ * repair priority. The stall/conceal decision is made again per released gap
12
+ * from the media that is actually missing, so a wrong classification can only
13
+ * lower a block's repair priority; it can never make playback wrong.
14
+ *
15
+ * Everything here is derived from catalog-authored timing and in-band MMTP
16
+ * evidence. There are no timers, no cadence heuristics, and no defaults: a
17
+ * track whose geometry cannot be derived exactly runs in the defined
18
+ * fail-closed mode `all-protected`, where every block is treated as possibly
19
+ * keyframe-bearing.
20
+ *
21
+ * All three players (moqtail, hang, Shaka) consume this one implementation.
22
+ */
23
+ /**
24
+ * Repair class of one FEC block.
25
+ *
26
+ * - `keyframe`: the block holds (or held) a RAP / MPU start.
27
+ * - `delta`: the block provably holds only non-RAP video frames.
28
+ * - `unknown`: neither could be proven; treated exactly like `keyframe`.
29
+ * - `audio`: an audio block.
30
+ */
31
+ export type BlockClass = 'keyframe' | 'delta' | 'unknown' | 'audio';
32
+ /** Repair priority. Lower is more urgent. */
33
+ export type RepairPriority = 0 | 1 | 2;
34
+ export type TrackKind = 'video' | 'audio';
35
+ /** P0 = keyframe/unknown (stall-preventing), P1 = audio, P2 = delta. */
36
+ export declare function repairPriorityForClass(blockClass: BlockClass): RepairPriority;
37
+ export type ClassifierMode = 'classifying' | 'all-protected';
38
+ /** Why a track runs `all-protected`. */
39
+ export type ClassifierReason = 'framerate-absent' | 'keyframe-cadence-absent' | 'keyframe-interval-not-integral' | 'block-spans-gop'
40
+ /**
41
+ * The catalog keyframe interval is not an exact integer number of ticks
42
+ * in the media track's own timescale (ISO-BMFF `mdhd`), so released RAP
43
+ * spacing cannot be verified and hold-last cannot predict the next RAP.
44
+ * Nothing is wrong with the stream; the cadence is simply unprovable.
45
+ */
46
+ | 'keyframe-interval-not-media-integral'
47
+ /**
48
+ * Another stream on this packetId was configured with its own geometry
49
+ * and this one was not, so no geometry provably belongs to it (ABR rungs
50
+ * sharing a packetId).
51
+ */
52
+ | 'stream-geometry-absent' | 'rap-not-mpu-start' | 'mpu-longer-than-gop' | 'block-not-contiguous' | 'rap-spacing-mismatch' | 'mpu-multiple-fragments' | 'block-wider-than-interleave';
53
+ /** Raw catalog timing for one track. Never a resolved cadence. */
54
+ export interface BlockClassifierGeometryInput {
55
+ readonly trackKind: TrackKind;
56
+ /** Catalog `framerate` (frames per second). */
57
+ readonly framerate?: number;
58
+ /** Catalog `fec.interleaveDepthMs`: the full FEC block span (§5.1). */
59
+ readonly interleaveDepthMs: number;
60
+ /** Catalog track `timescale` for `keyframeIntervalTicks`. */
61
+ readonly timescale?: number;
62
+ /** Catalog `keyframeIntervalTicks` (preferred when the timescale is present). */
63
+ readonly keyframeIntervalTicks?: number;
64
+ /** Catalog `keyframeIntervalMs`. */
65
+ readonly keyframeIntervalMs?: number;
66
+ }
67
+ /** Exact keyframe interval as a rational number of seconds: ticks / timescale. */
68
+ export interface KeyframeInterval {
69
+ readonly ticks: number;
70
+ readonly timescale: number;
71
+ }
72
+ export type BlockClassifierGeometry = {
73
+ readonly trackKind: 'audio';
74
+ } | {
75
+ readonly trackKind: 'video';
76
+ readonly mode: 'classifying';
77
+ /** F: one frame's duration in milliseconds (1000 / framerate). */
78
+ readonly frameDurationMs: number;
79
+ /** D: media units per FEC block (deriveFecInterleaveDepth). */
80
+ readonly interleaveUnits: number;
81
+ /** G: frames per GOP. */
82
+ readonly gopFrames: number;
83
+ readonly keyframeInterval: KeyframeInterval;
84
+ } | {
85
+ readonly trackKind: 'video';
86
+ readonly mode: 'all-protected';
87
+ readonly reason: ClassifierReason;
88
+ };
89
+ /**
90
+ * Derive the per-track classifier geometry from raw catalog fields.
91
+ *
92
+ * `all-protected` is the policy's defined fail-closed state, not a default:
93
+ * it is returned with the exact reason. The only throw is for a value the
94
+ * catalog validator already rejects (a non-positive block span).
95
+ */
96
+ export declare function deriveBlockClassifierGeometry(input: BlockClassifierGeometryInput): BlockClassifierGeometry;
97
+ /**
98
+ * The keyframe interval expressed in a media track's timescale, or null when
99
+ * the geometry is not `classifying` or the interval is not an exact integer
100
+ * number of media ticks.
101
+ */
102
+ export declare function keyframeIntervalMediaTicks(geometry: BlockClassifierGeometry, mediaTimescale: number): bigint | null;
103
+ /**
104
+ * In-band evidence from ONE first-arrival source symbol received from the
105
+ * network. Recovered symbols and repair symbols never contribute, and the
106
+ * MFU `priority > 0x80` hint is not evidence.
107
+ */
108
+ export interface SourceSymbolEvidence {
109
+ /** The MMTP header R (RAP) bit. */
110
+ readonly rap: boolean;
111
+ /** MPU_sequence_number, when parsed from this packet. */
112
+ readonly mpu?: number;
113
+ /**
114
+ * 0-based sample position within the MPU: the MFU DU-header
115
+ * `sample_number` minus one (ISO/IEC 23008-1 numbers samples from 1, and
116
+ * the parser rejects `sample_number` 0). Present only when this packet
117
+ * carried a DU header.
118
+ */
119
+ readonly idx?: number;
120
+ /** movie_fragment_sequence_number from the DU header, when present. */
121
+ readonly movieFragment?: number;
122
+ /**
123
+ * DU-header `offset`: the data unit's authored byte position within its
124
+ * sample (0 for a whole-sample data unit, the partition boundary for a
125
+ * subsample data unit). Present only with `idx`; absent reads as 0.
126
+ */
127
+ readonly offset?: number;
128
+ /**
129
+ * The MMTP header packet_sequence_number (contiguous per packet_id). Not
130
+ * classification evidence: FECManager uses it to bound how many blocks the
131
+ * producer can have started between two source symbols, so an outage is
132
+ * never mistaken for a source restart.
133
+ */
134
+ readonly packetSequenceNumber?: number;
135
+ }
136
+ export type ReclassificationEvidence = 'rap' | 'mpu-span' | 'window' | 'classifier-disabled';
137
+ export type ClassifierChange = {
138
+ readonly kind: 'reclassified';
139
+ readonly sbn: number;
140
+ readonly from: BlockClass;
141
+ readonly to: BlockClass;
142
+ readonly evidence: ReclassificationEvidence;
143
+ } | {
144
+ readonly kind: 'mode';
145
+ readonly mode: 'all-protected';
146
+ readonly reason: ClassifierReason;
147
+ };
148
+ /**
149
+ * Per-stream block classifier.
150
+ *
151
+ * Classes only move toward more protection or narrower evidence:
152
+ * `unknown→delta` and `unknown→keyframe` / `delta→keyframe` on evidence, and
153
+ * `delta→unknown` when an invariant disables classification. `keyframe` is
154
+ * terminal.
155
+ *
156
+ * The delta window rule rests on three premises, each guarded by an
157
+ * invariant that fires on positive evidence only:
158
+ *
159
+ * - P1: the source packets of one block are one contiguous run of the
160
+ * stream's authored order, and blocks follow each other in SBN order
161
+ * (`block-not-contiguous`). The producer assigns SS_IDs in authored order
162
+ * and a block is the SS_ID range [SBN*K, SBN*K + K), so this holds for a
163
+ * block that closes at K symbols in the middle of a frame: that frame's
164
+ * fragments then land in two ADJACENT blocks, which is still one run each.
165
+ * A frame split across adjacent blocks is not a violation.
166
+ * - P2: that run touches at most D media units, counting a frame continued
167
+ * from the previous block (`block-wider-than-interleave`). The producer
168
+ * counts a media-unit boundary only once the open block holds a symbol.
169
+ * - P3: an MPU starts with its only RAP and holds at most G frames
170
+ * (`rap-not-mpu-start`, `mpu-longer-than-gop`, `rap-spacing-mismatch`), in
171
+ * one movie fragment (`mpu-multiple-fragments`).
172
+ *
173
+ * P1 and P2 are what make a block's frames contiguous and lie within
174
+ * [idxMax − D + 1, idxMin + D − 1] of its MPU. What refutes P1 is a pair of
175
+ * source packets whose wire-stated authored order and SBN order disagree:
176
+ * a later MPU in an earlier block, a later data unit of one MPU (by
177
+ * movie_fragment_sequence_number, sample_number, then DU offset) in an
178
+ * earlier block, or one data unit in two blocks. That is the signature of a
179
+ * round-robin interleave, which scatters one run over several concurrent
180
+ * blocks. Non-adjacency alone is not: a sample larger than K packets
181
+ * legitimately spans blocks SBN..SBN+n.
182
+ */
183
+ export declare class BlockClassifier {
184
+ #private;
185
+ constructor(geometry: BlockClassifierGeometry);
186
+ get geometry(): BlockClassifierGeometry;
187
+ get mode(): ClassifierMode;
188
+ get reason(): ClassifierReason | null;
189
+ /**
190
+ * Whether "same MPU on both sides of a gap" still proves the gap held no
191
+ * RAP. It stops holding for the rest of the epoch once a RAP was received
192
+ * inside an MPU or an MPU ran longer than a GOP.
193
+ */
194
+ get mpuBoundsRaps(): boolean;
195
+ /** Begin a fresh epoch (catalog change or track reset). */
196
+ reset(geometry?: BlockClassifierGeometry): void;
197
+ /**
198
+ * Retire this classifier (its stream moves to a new catalog epoch). Every
199
+ * block it had classified `delta` loses the evidence behind that class and
200
+ * reads `unknown` from now on; the returned changes say so.
201
+ */
202
+ retire(): ClassifierChange[];
203
+ /**
204
+ * The stream's SBN sequence restarted (FECManager source discontinuity:
205
+ * a publisher restart, or the SS_ID space wrapped). Authored order and SBN
206
+ * order are comparable only within one continuous sequence, so the P1
207
+ * ledger starts again.
208
+ */
209
+ noteSourceDiscontinuity(): void;
210
+ /** Register a block that exists without evidence (a vanished block). */
211
+ touch(sbn: number): void;
212
+ /** Forget a resolved block. */
213
+ forget(sbn: number): void;
214
+ classOf(sbn: number): BlockClass;
215
+ /** Record one first-arrival source symbol's evidence for block `sbn`. */
216
+ observe(sbn: number, evidence: SourceSymbolEvidence): ClassifierChange[];
217
+ /**
218
+ * Record a RAP frame released in order. Released MPU-start RAPs of MPUs m
219
+ * and m+n must be exactly n keyframe intervals apart in the media
220
+ * timescale, compared as integers.
221
+ *
222
+ * Comparing only consecutive MPUs would miss exactly the case the window
223
+ * rule cannot survive: a short MPU whose successor's RAP was lost (that
224
+ * RAP-bearing block is the one a wrong G calls delta), because the next
225
+ * released RAP then belongs to m+2. Every MPU is one interval long, so the
226
+ * span to any later released RAP proves or refutes all MPUs in between.
227
+ */
228
+ noteReleasedRap(mpu: number, presentationTime: bigint, mediaTimescale: number): ClassifierChange[];
229
+ }
230
+ export interface GapStreamIdentity {
231
+ readonly packetId: number;
232
+ /** Non-empty catalog identity, or null when the producer has no track name. */
233
+ readonly catalogTrackName: string | null;
234
+ }
235
+ /** What the sink knows about one side of a released gap. */
236
+ export interface GapFrameEvidence {
237
+ /**
238
+ * Codec-aware RAP check: `MmtpContainerParser.isKeyframe(data, rapFlag,
239
+ * codec)`, bitstream-only for recovered frames. Never the priority hint.
240
+ */
241
+ readonly rap: boolean;
242
+ /**
243
+ * MPU_sequence_number of the frame. Omit it once the stream showed that
244
+ * an MPU boundary does not bound its RAPs (`BlockClassifier.mpuBoundsRaps`):
245
+ * same-MPU then no longer proves a gap lost only deltas.
246
+ */
247
+ readonly mpu?: number;
248
+ /** 0-based sample position within the MPU, when the geometry verifies it. */
249
+ readonly idx?: number;
250
+ /** Authored presentation time in `timescale` ticks. */
251
+ readonly pts?: bigint;
252
+ /** Authored sample duration in `timescale` ticks. */
253
+ readonly durationTicks?: number;
254
+ /** The media timescale of `pts` and `durationTicks`. */
255
+ readonly timescale?: number;
256
+ }
257
+ export type FrameGapAction = 'stall' | 'conceal';
258
+ export type FrameGapReason = 'rap-lost' | 'rap-unknown' | 'discontinuity' | 'delta-lost' | 'rap-next' | 'audio-gap' | 'audio-discontinuity';
259
+ /**
260
+ * The decision attached to the first frame released after a gap
261
+ * (`RoutedFrameMeta.gapBefore`). It is the same frozen object the manager
262
+ * emits as its `gap` repair lifecycle event, so a sink that acts on the frame
263
+ * and an observer that counts events see one fact.
264
+ */
265
+ export interface FrameGapDecision {
266
+ readonly version: 2;
267
+ readonly type: 'gap';
268
+ readonly stream: GapStreamIdentity;
269
+ readonly trackKind: TrackKind;
270
+ readonly action: FrameGapAction;
271
+ readonly reason: FrameGapReason;
272
+ /** FEC blocks in the gap whose media was lost (failed or vanished). */
273
+ readonly blocks: readonly number[];
274
+ /** Missing video frames or audio access units, when exactly known. */
275
+ readonly missingFrames: number | null;
276
+ /** Authored duration of the missing media in milliseconds, when known. */
277
+ readonly missingMs: number | null;
278
+ /** Manager epoch of the stream when the decision was made. */
279
+ readonly epoch: number;
280
+ }
281
+ export interface DecideGapInput {
282
+ readonly stream: GapStreamIdentity;
283
+ readonly trackKind: TrackKind;
284
+ /** Last frame released before the gap. */
285
+ readonly before: GapFrameEvidence;
286
+ /** First frame released after the gap. */
287
+ readonly after: GapFrameEvidence;
288
+ /** The stream restarted (FEC SBN went backwards or the publisher reset). */
289
+ readonly discontinuity: boolean;
290
+ readonly blocks: readonly number[];
291
+ /**
292
+ * The most media units the gap can hold: the FEC blocks spanned from the
293
+ * frame before to the frame after, times D (media units per block,
294
+ * ceil(interleaveDepthMs / unit duration), §5.1). A block touches at most D
295
+ * units whether it closes at D or at K symbols. Null when the span or D is
296
+ * unknown. An audio PTS delta that implies more AUs than this is a clock
297
+ * jump, not loss, and re-anchors instead of concealing every slot.
298
+ */
299
+ readonly maxMissingUnits: number | null;
300
+ readonly epoch: number;
301
+ }
302
+ /**
303
+ * Pure stall/conceal decision for the first frame released after a gap.
304
+ *
305
+ * Video stalls only when a RAP may be inside the gap: the frame after it is
306
+ * not a RAP and either sits in another MPU (`rap-lost`) or the MPU cannot be
307
+ * proven on both sides (`rap-unknown`), or the stream restarted
308
+ * (`discontinuity`). A gap inside one MPU lost only deltas (`delta-lost`) and
309
+ * a RAP after the gap resynchronises by itself (`rap-next`). Audio never
310
+ * stalls: an exact gap is concealed per access unit (`audio-gap`), anything
311
+ * else re-anchors at the next frame (`audio-discontinuity`).
312
+ */
313
+ export declare function decideGap(input: DecideGapInput): FrameGapDecision;
314
+ //# sourceMappingURL=block-policy.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"block-policy.d.ts","sourceRoot":"","sources":["../src/block-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAA;AAEnE,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAEtC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;AAEzC,wEAAwE;AACxE,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,UAAU,GAAG,cAAc,CAU7E;AAID,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,eAAe,CAAA;AAE5D,wCAAwC;AACxC,MAAM,MAAM,gBAAgB,GAExB,kBAAkB,GAClB,yBAAyB,GACzB,gCAAgC,GAChC,iBAAiB;AACnB;;;;;GAKG;GACD,sCAAsC;AACxC;;;;GAIG;GACD,wBAAwB,GAExB,mBAAmB,GACnB,qBAAqB,GACrB,sBAAsB,GACtB,sBAAsB,GACtB,wBAAwB,GACxB,6BAA6B,CAAA;AAEjC,kEAAkE;AAClE,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,iFAAiF;IACjF,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAA;IACvC,oCAAoC;IACpC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CACrC;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAC/B;IACE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,yBAAyB;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAA;CAC5C,GACD;IACE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAClC,CAAA;AAyBL;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,4BAA4B,GAClC,uBAAuB,CA8CzB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,uBAAuB,EACjC,cAAc,EAAE,MAAM,GACrB,MAAM,GAAG,IAAI,CASf;AAID;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,uEAAuE;IACvE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAA;CACvC;AAED,MAAM,MAAM,wBAAwB,GAAG,KAAK,GAAG,UAAU,GAAG,QAAQ,GAAG,qBAAqB,CAAA;AAE5F,MAAM,MAAM,gBAAgB,GACxB;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,wBAAwB,CAAA;CAC5C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAClC,CAAA;AA0BL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,eAAe;;gBA0Bd,QAAQ,EAAE,uBAAuB;IAO7C,IAAI,QAAQ,IAAI,uBAAuB,CAEtC;IAED,IAAI,IAAI,IAAI,cAAc,CAEzB;IAED,IAAI,MAAM,IAAI,gBAAgB,GAAG,IAAI,CAEpC;IAED;;;;OAIG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED,2DAA2D;IAC3D,KAAK,CAAC,QAAQ,GAAE,uBAAwC,GAAG,IAAI;IAgB/D;;;;OAIG;IACH,MAAM,IAAI,gBAAgB,EAAE;IAgB5B;;;;;OAKG;IACH,uBAAuB,IAAI,IAAI;IAI/B,wEAAwE;IACxE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIxB,+BAA+B;IAC/B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;IAKhC,yEAAyE;IACzE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,gBAAgB,EAAE;IAmCxE;;;;;;;;;;OAUG;IACH,eAAe,CACb,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,MAAM,EACxB,cAAc,EAAE,MAAM,GACrB,gBAAgB,EAAE;CA4NtB;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CACzC;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,CAAA;AAEhD,MAAM,MAAM,cAAc,GACtB,UAAU,GACV,aAAa,GACb,eAAe,GACf,YAAY,GACZ,UAAU,GACV,WAAW,GACX,qBAAqB,CAAA;AAEzB;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,sEAAsE;IACtE,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAkEjE"}