@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.
- package/README.md +44 -3
- package/dist/block-policy.d.ts +314 -0
- package/dist/block-policy.d.ts.map +1 -0
- package/dist/block-policy.js +466 -0
- package/dist/block-policy.js.map +7 -0
- package/dist/browser-runtime.js +2796 -573
- package/dist/browser-runtime.js.map +4 -4
- package/dist/catalog-fec-params.d.ts +28 -4
- package/dist/catalog-fec-params.d.ts.map +1 -1
- package/dist/catalog-fec-params.js +28 -1
- package/dist/catalog-fec-params.js.map +3 -3
- package/dist/cmaf-block-assembler.d.ts +25 -11
- package/dist/cmaf-block-assembler.d.ts.map +1 -1
- package/dist/cmaf-block-assembler.js +76 -177
- package/dist/cmaf-block-assembler.js.map +3 -3
- package/dist/cmaf-group-batcher.js.map +1 -1
- package/dist/cmcd-producer.d.ts.map +1 -1
- package/dist/cmcd-producer.js +0 -3
- package/dist/cmcd-producer.js.map +2 -2
- package/dist/conceal-timeline.d.ts +123 -0
- package/dist/conceal-timeline.d.ts.map +1 -0
- package/dist/conceal-timeline.js +122 -0
- package/dist/conceal-timeline.js.map +7 -0
- package/dist/duplicate-ledger.d.ts +197 -0
- package/dist/duplicate-ledger.d.ts.map +1 -0
- package/dist/duplicate-ledger.js +226 -0
- package/dist/duplicate-ledger.js.map +7 -0
- package/dist/fec-manager.d.ts +113 -23
- package/dist/fec-manager.d.ts.map +1 -1
- package/dist/fec-manager.js +879 -131
- package/dist/fec-manager.js.map +4 -4
- package/dist/fec-worker-setup.js +0 -8
- package/dist/fec-worker-setup.js.map +2 -2
- package/dist/index.d.ts +7 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +27 -3
- package/dist/index.js.map +2 -2
- package/dist/media-router.d.ts +5 -2
- package/dist/media-router.d.ts.map +1 -1
- package/dist/media-router.js +13 -1
- package/dist/media-router.js.map +2 -2
- package/dist/mmtp-container-parser.d.ts +85 -0
- package/dist/mmtp-container-parser.d.ts.map +1 -1
- package/dist/mmtp-container-parser.js +271 -4
- package/dist/mmtp-container-parser.js.map +2 -2
- package/dist/mmtp-container-parser.no-modules.js +273 -5
- package/dist/mmtp-container-parser.no-modules.js.map +3 -3
- package/dist/mmtp-decode-pipeline.d.ts +7 -1
- package/dist/mmtp-decode-pipeline.d.ts.map +1 -1
- package/dist/mmtp-decode-pipeline.js +279 -8
- package/dist/mmtp-decode-pipeline.js.map +2 -2
- package/dist/mmtp-router.d.ts +88 -12
- package/dist/mmtp-router.d.ts.map +1 -1
- package/dist/mmtp-router.js +1031 -247
- package/dist/mmtp-router.js.map +3 -3
- package/dist/mmtp-to-cmaf.d.ts +0 -12
- package/dist/mmtp-to-cmaf.d.ts.map +1 -1
- package/dist/mmtp-to-cmaf.js +0 -62
- package/dist/mmtp-to-cmaf.js.map +2 -2
- package/dist/multicast-manager.d.ts +148 -16
- package/dist/multicast-manager.d.ts.map +1 -1
- package/dist/multicast-manager.js +2445 -477
- package/dist/multicast-manager.js.map +4 -4
- package/dist/multicast-transport.d.ts.map +1 -1
- package/dist/multicast-transport.js +119 -22
- package/dist/multicast-transport.js.map +3 -3
- package/dist/no-modules.js +271 -4
- package/dist/no-modules.js.map +2 -2
- package/dist/repair-fetch.d.ts +172 -23
- package/dist/repair-fetch.d.ts.map +1 -1
- package/dist/repair-fetch.js +235 -85
- package/dist/repair-fetch.js.map +4 -4
- package/dist/wasm-mmtp-container-parser.js +271 -4
- package/dist/wasm-mmtp-container-parser.js.map +2 -2
- package/node_modules/@blockcast/fec-worker/README.md +4 -4
- package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.d.ts +0 -2
- package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.d.ts.map +1 -1
- package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.js +0 -8
- package/node_modules/@blockcast/fec-worker/dist/fec-worker-client.js.map +1 -1
- package/node_modules/@blockcast/fec-worker/dist/fec-worker-types.d.ts +1 -7
- package/node_modules/@blockcast/fec-worker/dist/fec-worker-types.d.ts.map +1 -1
- package/node_modules/@blockcast/fec-worker/dist/fec-worker.js +4 -33
- package/node_modules/@blockcast/fec-worker/dist/fec-worker.js.map +2 -2
- package/node_modules/@blockcast/fec-worker/src/fec-worker-client.ts +0 -9
- package/node_modules/@blockcast/fec-worker/src/fec-worker-types.ts +1 -4
- package/node_modules/@blockcast/fec-worker/src/fec-worker.ts +15 -51
- package/package.json +14 -6
- package/schemas/catalog.schema.json +5 -0
- package/src/block-policy.ts +903 -0
- package/src/catalog-fec-params.ts +62 -5
- package/src/cmaf-block-assembler.ts +60 -151
- package/src/cmcd-producer.ts +0 -5
- package/src/conceal-timeline.ts +255 -0
- package/src/duplicate-ledger.ts +372 -0
- package/src/fec-manager.ts +742 -139
- package/src/index.ts +53 -1
- package/src/media-router.ts +22 -4
- package/src/mmtp-container-parser.ts +421 -1
- package/src/mmtp-decode-pipeline.ts +23 -6
- package/src/mmtp-router.ts +701 -93
- package/src/mmtp-to-cmaf.ts +1 -101
- package/src/multicast-manager.ts +587 -89
- package/src/multicast-transport.ts +108 -19
- 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`, `
|
|
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":"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"}
|