@blockcast/mmt-container 0.1.0 → 0.3.0-main.ef68de90edb3

package/src/index.ts

@@ -6,22 +6,7 @@
  * @packageDocumentation
  */
 
-// MMTP Parser
-export {
-  type MMTPHeader,
-  type MPUHeader,
-  type MMTPPacket,
-  MMTP_HEADER_SIZE,
-  MPU_HEADER_SIZE,
-  MFU_DU_HEADER_SIZE,
-  parseMMTPHeader,
-  unwrapMMTP,
-  parseMPUHeader,
-  extractNALUnit,
-  extractTimestamp,
-  isFecRepairPacket,
-  hasFecPayloadId,
-} from './mmtp.js'
+export type { AuthoredTiming } from './authored-timing.js'
 
 // MFU Reassembler
 export {
@@ -29,16 +14,600 @@ export {
   type ReassembledMFU,
   type ReassemblerStats,
   type MFUReassemblerOptions,
+  type MfuReassemblerBackend,
+  type MmtpSourcePath,
   MFUReassembler,
+  isMfuReassemblyError,
+  MfuReassemblyError,
+  type MfuReassemblyErrorCode,
   createFragment,
   processMMTPWithReassembly,
 } from './mfu-reassembler.js'
 
-// LOC FEC Extensions
+// Sample combiner: combines subsample data units (moqcast #37) of one
+// timed sample, each already reassembled by MFUReassembler, back into one
+// contiguous sample.
+export {
+  type CombinedSample,
+  type SampleCombinerStats,
+  SampleCombiner,
+  SampleCombineError,
+  type SampleCombineErrorCode,
+} from './sample-combiner.js'
+
+// fMP4 data-unit completion policy (BLO-13291)
+export { isCompleteFmp4DataUnit } from './fmp4-completion.js'
+
+
+// source-auth (authenticated-manifest / Merkle) is intentionally NOT re-exported
+// from the eager index barrel. It statically imports blake3 from @noble/hashes,
+// and re-exporting it here pulls that bare specifier into every browser consumer
+// of @blockcast/mmt-container (the moq-lib / shred / moqtail players load the
+// barrel as raw ESM via an import map, where @noble/hashes has no mapping →
+// "Failed to resolve module specifier". No browser player uses source-auth.)
+// Consumers that need it import the dedicated subpath: '@blockcast/mmt-container/source-auth'.
+// The same rule covers the @blockcast/mmt-manifest-verify surface (ManifestVerifier et al.):
+// import it from that package (or the subpath above) directly, never from this barrel.
+
+// H.264/AVC + H.265/HEVC Codec Utilities
+export {
+  type AvcCInfo,
+  type AacAscInfo,
+  type SpsPps,
+  type FallbackAvcCOptions,
+  type HevcParameterSets,
+  type H264KeyframeDetectionOptions,
+  type H264AvccSample,
+  type H264SampleFormat,
+  type H264NalUnitFormat,
+  type H264NalUnitSample,
+  extractAvcCFromInitSegment,
+  extractAacAscFromInitSegment,
+  normalizeMmtpInitSegment,
+  generateFallbackAvcC,
+  extractSpsPpsFromAvcC,
+  avccToAnnexB,
+  extractCodecDescriptionFromAnnexB,
+  codecStringFromAvcC,
+  isAnnexB,
+  isCompleteAvccSample,
+  findAnnexBStartCode,
+  splitAnnexBNalUnits,
+  annexBToAvcc,
+  normalizeH264SampleToAvcc,
+  splitH264SampleNalUnits,
+  classifyH264Keyframe,
+  detectH264Keyframe,
+  mmtpTimestampToMicros,
+  isFmp4InitSegment,
+  wrapAdtsFrame,
+  // HEVC (BLO-7764): build the hvcC description WebCodecs requires for length-prefixed H.265.
+  isHevcCodec,
+  removeEmulationPrevention,
+  splitAvccNalUnits,
+  extractHevcParameterSets,
+  generateHvcCFromParameterSets,
+  extractHevcCodecDescription,
+  hevcVclOnly,
+  // HEVC receive path (BLO-35597): catalog-selected family, IRAP keyframes,
+  // SPS-derived codec string, MSE sample normalization.
+  type VideoSampleEntry,
+  type VideoCodecFamily,
+  type HevcSpsInfo,
+  type HevcCmafSample,
+  videoSampleEntryFromCodecString,
+  videoCodecFamily,
+  HEVC_NAL_UNIT_TYPE,
+  HEVC_NAL_HEADER_LENGTH,
+  hevcNalUnitType,
+  isHevcIrapNalUnitType,
+  parseHevcSps,
+  hevcCodecStringFromSps,
+  classifyHevcKeyframe,
+  detectHevcKeyframe,
+  normalizeHevcSampleToLengthPrefixed,
+  prepareHevcCmafSample,
+} from './codec-utils.js'
+
+// LOC FEC Extensions (draft-ramadan-moq-fec §5.3, object extension 0x11)
 export {
   LOCHeaderExtensionId,
-  FEC_PAYLOAD_ID_MAX,
-  fecPack,
-  fecUnpack,
-  FecPayloadId,
+  FEC_SS_ID_MAX,
+  FEC_SOURCE_INFO_LEN,
+  encodeFecSourceInfo,
+  decodeFecSourceInfo,
+  FecSourceInfo,
+  AuthTag,
 } from './loc.js'
+
+// CARP Catalog Extensions (draft-law-ramadan-moq-carp-reliability §3-4)
+// + Track Timing (draft-ramadan-moq-mmt-00 §4.4.4)
+export {
+  type FecAlgorithm,
+  type FecCatalogConfig,
+  isFecCatalogConfig,
+  type MulticastProtocol,
+  type MulticastTrack,
+  type MulticastTrackObject,
+  type MulticastEndpoint,
+  type AmtDiscovery,
+  type MulticastCatalogConfig,
+  type NetworkSource,
+  isMulticastTrackObject,
+  isMulticastEndpoint,
+  isMulticastCatalogConfig,
+  type TrackTimingConfig,
+  isTrackTimingConfig,
+  resolveGroupDurationTicks,
+  resolveGroupDurationMs,
+  validateSwitchingSetTiming,
+  type CmsfCatalog,
+  type CmsfCatalogErrorCode,
+  CmsfCatalogValidationError,
+  validateCmsfMmtpCatalog,
+  type ArchiveConfig,
+  archiveOrigin,
+} from './carp-catalog.js'
+
+// Multicast input contract — validator + builder for publisher-emitted
+// catalogs (draft-ramadan-moq-multicast-00 §4.1, BLO-3323 A.1).
+// `multicastFromEnv` is the env-var helper used by FFmpeg and the
+// cast bridge (BLO-3337).
+export {
+  type MulticastInput,
+  type MulticastEndpointInput,
+  type MulticastInputErrorKind,
+  MulticastInputError,
+  multicastFromConfig,
+  multicastFromEnv,
+} from './multicast-input.js'
+
+// Phase 14 catalog override hook (test harness injects
+// globalThis.__PHASE14_CATALOG_OVERRIDE; see 7point-validation.test.mjs)
+export {
+  type Phase14OverrideTrack,
+  type Phase14CatalogOverride,
+  getPhase14CatalogOverride,
+  mergeOverrideIntoHangRenditions,
+  mergeOverrideIntoCmsfTracks,
+} from './phase14-catalog-override.js'
+
+// Multicast Unwrap (container-aware MMTP dispatch)
+export {
+  type MulticastContainerContract,
+  type MulticastContainerErrorCode,
+  type FecPayloadId as MulticastFecPayloadId,
+  type MulticastFrame,
+  MulticastContainerContractError,
+  validateMulticastContainerContract,
+  unwrapMulticastPacket,
+} from './multicast-unwrap.js'
+
+// Timestamp Codec — container-format-agnostic timestamp encoding/decoding
+export {
+  type ContainerFormat,
+  type LocHeader,
+  encodeTimestamp,
+  decodeTimestamp,
+  getTimestampSize,
+  decodeLocHeader,
+  decodeLocTimestamp,
+  encodeLocTimestamp,
+} from './timestamp-codec.js'
+
+// MMTP → CMAF conversion (draft-ramadan-moq-mmt §5.3)
+export {
+  MmtpToCmaf,
+  encodeDataSegment,
+  encodeMultiSampleSegment,
+  buildVideoInitSegment,
+  buildHevcVideoInitSegment,
+  buildAudioInitSegment,
+  generateSilenceFrame,
+} from './mmtp-to-cmaf.js'
+
+// MMTP Signaling — packet type detection and classification
+export {
+  type PacketClass,
+  getPacketType,
+  isSignalingPacket,
+  isSourcePacket,
+  classifyPacket,
+} from './signaling.js'
+
+// FEC Block → CMAF Segment Assembler
+export {
+  CmafBlockAssembler,
+  type CmafBlockSample,
+  type CmafSampleOrderPolicy,
+  type CmafSampleOrderStats,
+  type CmafEmitStats,
+  type CmafAudioConcealStats,
+  type BlockAssemblerConfig,
+} from './cmaf-block-assembler.js'
+
+// MoQ Group → CMAF Segment Batcher
+export {
+  CmafGroupBatcher,
+  type CmafGroupBatcherConfig,
+} from './cmaf-group-batcher.js'
+
+// FEC Manager (codec-agnostic FEC decode service)
+export {
+  FECManager,
+  type FECManagerConfig,
+  type FecDecoderUnavailableEvent,
+  type FecDecoderUnavailableReason,
+  type FecFallbackDecoder,
+  type WasmFecDecoder,
+  type FecStats,
+  type MulticastSymbolDelivery,
+  type FecBlockResolution,
+  type RepairVia,
+} from './fec-manager.js'
+
+// MMTP Router (packet processing + frame routing)
+export {
+  MmtpRouter,
+  KEYFRAME_LOST_TIMEOUT_SLACK,
+  type FrameCallback,
+  type FECManagerLike,
+  type MmtpIngressContext,
+  type MmtpStreamIdentity,
+  type RoutedPacketMeta,
+  type StagedStreamSwitch,
+  type StreamSwitchCommit,
+  type StreamSwitchCommitReason,
+  type StreamSwitchOptions,
+  type StreamSwitchPosition,
+  type TrackPacketCallback,
+} from './mmtp-router.js'
+
+// MmtpContainerParser (unified, transport-agnostic)
+export {
+  MmtpContainerParser,
+  type MmtpParserConfig,
+  type MmtpParserRecord,
+  type MmtpParserFeedStats,
+  type MmtpFeedDropReason,
+  type MmtpFeedOutcomeKey,
+  type TrackInfo,
+  type MmtpReorderStats,
+  type MmtpReorderFrameDiagnostics,
+  type MmtpReorderStreamDiagnostics,
+  type FrameMeta as ParserFrameMeta,
+  type PacketInfo,
+  type ParsedMmtpPacket,
+} from './mmtp-container-parser.js'
+
+export {
+  datagramMfuReassembly,
+  reliableMoqMfuReassembly,
+  mmtpFrameReorderWindowFrames,
+  mfuReassemblyTimeoutMs,
+  type MfuReassemblyPolicy,
+  type MmtpTrackType,
+  type ReliableMoqReassemblyOptions,
+} from './mfu-reassembly-policy.js'
+
+export {
+  WasmMfuReassembler,
+  resolveGlobalMmtWasmBindings,
+  type MmtWasmBindings,
+  type WasmMfuReassemblerOptions,
+} from './wasm-mfu-reassembler.js'
+
+export {
+  createWasmMmtpContainerParser,
+  type WasmMmtpParserConfig,
+} from './wasm-mmtp-container-parser.js'
+
+// FEC Codec (generic, algorithm-pluggable)
+export {
+  type FecCodec,
+  NoneCodec,
+  ReedSolomonCodec,
+  createFecCodec,
+} from './fec-codec.js'
+
+// Multicast Transport (SSM join/socket/watchdog)
+export {
+  MulticastTransport,
+  type MulticastFailbackReason,
+  type MulticastJoinDeclineReason,
+  type MulticastJoinOutcome,
+  type MulticastJoinProviderError,
+  type MulticastJoinStats,
+  type MulticastTransportConfig,
+  type ResolvedMulticastTransport,
+} from './multicast-transport.js'
+
+// Multicast Manager (backwards-compat facade composing all three)
+export {
+  MulticastManager,
+  forwardRepairLifecycleEvents,
+  isRepairLifecycleEvent,
+  REPAIR_LIFECYCLE_EVENT_TYPE,
+  REPAIR_LIFECYCLE_LOG_PREFIX,
+  type MulticastEndpointConfig,
+  type MultiTrackCatalog,
+  type MultiTrackCatalogTrack,
+  type WasmFecDecoderFactory,
+  type RepairBlockIdentity,
+  type RepairLifecycleApplicationEvent,
+  type RepairLifecycleEventOptions,
+  type RepairLifecycleEventFactory,
+  type RepairLifecycleEventTarget,
+  type RepairLifecycleSource,
+  type RepairLifecycleEvent,
+  type RepairLifecycleObserver,
+  type RepairStreamIdentity,
+  type BlockPolicyStats,
+  type RenditionSwitch,
+  type RenditionSwitchCancel,
+  type RenditionSwitchRequest,
+  type RenditionSwitchState,
+} from './multicast-manager.js'
+
+// Keyframe-protected FEC repair policy: block classification, repair
+// priority, and the stall/conceal decision every player applies.
+export {
+  BlockClassifier,
+  decideGap,
+  deriveBlockClassifierGeometry,
+  keyframeIntervalMediaTicks,
+  repairPriorityForClass,
+  type BlockClass,
+  type BlockClassifierGeometry,
+  type BlockClassifierGeometryInput,
+  type ClassifierChange,
+  type ClassifierMode,
+  type ClassifierReason,
+  type DecideGapInput,
+  type FrameGapAction,
+  type FrameGapDecision,
+  type FrameGapReason,
+  type GapFrameEvidence,
+  type GapStreamIdentity,
+  type KeyframeInterval,
+  type ReclassificationEvidence,
+  type RepairPriority,
+  type SourceSymbolEvidence,
+  type TrackKind,
+} from './block-policy.js'
+
+// Sink-side concealment: hold last good frame, exact audio gap sizing.
+export {
+  AudioGapConcealer,
+  HoldLastTimeline,
+  videoConcealModeForCodec,
+  type AudioAccessUnit,
+  type AudioGapConcealerStats,
+  type AudioGapPlan,
+  type HoldLastTimelineOptions,
+  type HoldLastTimelineStats,
+  type TimelineEmit,
+  type TimelineSample,
+  type VideoConcealMode,
+} from './conceal-timeline.js'
+
+// FEC Worker Setup (shared fec-setup helper)
+export {
+  setupFecWorkerForTrack,
+  type FecWorkerAssetUrls,
+  type FecWorkerSetupOptions,
+  type FecWorkerSetupResult,
+} from './fec-worker-setup.js'
+
+// Media Router (shared MoQ ↔ multicast source arbitration)
+export {
+  MediaRouter,
+  TrackSourceConflictError,
+  type MediaRouterOptions,
+  type TrackSource,
+  type SetTrackSourceOptions,
+  type MigrationPolicy,
+  type FrameMeta as RouterFrameMeta,
+  type FrameKind,
+  type SourceKind,
+} from './media-router.js'
+
+// Group-alignment primitive — shared with Go sender + Rust relay.
+// See align.ts docstring for cross-language contract. Authoritative form
+// is integer-ticks (groupIdForTicks); seconds-form is the legacy ramp.
+export {
+  groupIdForTicks,
+  groupIdFor,
+  secondsFromTicks,
+  asSeconds,
+  driftCheck,
+  type Seconds,
+  type DriftCheckResult,
+} from './align.js'
+
+// Audio Ring Buffer — DEPRECATED: canonical location is @blockcast/mmt-render/audio.
+// Kept here for backwards compat with consumers not yet migrated to mmt-render.
+// The mmt-render version includes warmup-delayed clock recovery + adaptive target fill.
+export {
+  AudioRingBuffer,
+  type AudioRingBufferConfig,
+} from './audio-ring-buffer.js'
+
+// MMTP Decode Pipeline (MoQ + multicast unified decode path)
+export {
+  MmtpDecodePipeline,
+  type PipelineFecClient,
+  type PipelineConfig,
+  type MmtpFeedStats,
+} from './mmtp-decode-pipeline.js'
+
+// Track Pipeline (per-track transport promotion + ABR)
+export {
+  TrackPipeline,
+  type TrackTransport,
+  type TrackTransportPreference,
+  type TransportCapabilityReport,
+  type TrackTransportResolution,
+  type TrackSourceFactory,
+} from './track-pipeline.js'
+
+// Track Pipeline Setup (shared wiring helper for both players)
+export {
+  setupTrackPipeline,
+  type TrackDescriptor,
+  type SetupTrackPipelineOptions,
+  type SetupTrackPipelineResult,
+} from './track-pipeline-setup.js'
+
+// Audio Init Data Parser (spec-compliant frame samples from initData)
+export {
+  parseAacFrameSamples,
+  parseAacSampleRate,
+  parseOpusFrameSamples,
+  frameSamplesFromInit,
+} from './audio-init-parser.js'
+
+// Transport Pool (ref-counted subscription lifecycle, PIM)
+export {
+  TransportPool,
+  type SubscriptionMode,
+  type DirectSocketHealth,
+  type Subscription,
+  type SubscriptionStats,
+  type AcquireOptions,
+  type TransportPoolOptions,
+} from './transport-pool.js'
+
+// Track Session + Session Manager (per-track state machine, Patent Claim 9)
+export {
+  TrackSession,
+  SessionManager,
+  MAX_TAKEOVER_DEADLINE_MS,
+  JOIN_DEFER_WARN_MS,
+  computeFecDeliveryWindowMs,
+  computeFecDeliveryWindowMediaUnits,
+  computeFecLossWindowMs,
+  type FecDeliveryWindowConfig,
+  type TrackState,
+  type TrackSessionConfig,
+  type SessionManagerCallbacks,
+  type MmtpTrackEvent,
+  type MmtpSessionCallbacks,
+} from './track-session.js'
+
+// FEC starvation detector (post-cutover repair-only/no-progress detection,
+// drives TrackSession lossDetected/lossRecovered — BLO-9413/D4)
+export {
+  FecStarvationDetector,
+  type FecStarvationSnapshot,
+  type FecStarvationDetectorConfig,
+} from './fec-starvation-detector.js'
+
+// CMCD Producer (x-bc-* vendor key telemetry, BLO-1044)
+export {
+  CmcdProducer,
+  type CmcdParams,
+  type CmcdProducerOptions,
+  type SnapshotData,
+  type TransportSnapshot,
+  type TransportTransitionEvent,
+} from './cmcd-producer.js'
+
+export {
+	catalogFecInterleaveMs,
+	resolveCatalogTrackFec,
+	type CatalogTrackRef,
+	type FecInterleaveCatalog,
+	type GroupDurationCatalog,
+	type KeyframeCadenceCatalog,
+	type TrackFecParams,
+	type TrackFecUnavailable,
+	catalogGroupDurationMs,
+	type GroupDurationRendition,
+	resolveCatalogTrackGroupDurationMs,
+	joinedRepairSymbolCount,
+	FEC_BLOCK_PROFILES,
+	isFecBlockProfile,
+	parseFecBlockProfile,
+	readFecBlockProfile,
+	type FecBlockProfile,
+	resolveRepairLayers,
+	catalogRepairTarget,
+	assembleRepairLayers,
+	assertRepairTrackReachable,
+	repairReachability,
+	type AssembleRepairLayersOptions,
+	type RepairReachability,
+	dependsTarget,
+	describeRepairTrack,
+	rejectRepairFieldsOnMediaTrack,
+	rejectRepairTrackGeometry,
+	REPAIR_TRACK_GEOMETRY_KEYS,
+	REPAIR_TRACK_ONLY_KEYS,
+	validateRepairTrackFields,
+	RepairContractError,
+	DEFAULT_REPAIR_PRIORITY,
+	MAX_ENCODING_SYMBOL_ID,
+	MAX_RAPTORQ_SOURCE_SYMBOLS,
+	MAX_REPAIR_SYMBOLS,
+	REPAIR_PRIORITY_MAX,
+	REPAIR_PRIORITY_MIN,
+	type RepairContractCode,
+	type RepairContractFail,
+	type RepairLayerCatalog,
+	type RepairLayerParams,
+	type RepairLayersResolution,
+	type RepairOverlayParams,
+	type RepairRenditionCatalog,
+	type RepairSourceGeometry,
+	type RepairTrackDescriptor,
+} from "./catalog-fec-params.js";
+
+// Typed FEC state (active with counters, or inactive with a reason) shared by
+// every player, resolved from catalog, transport policy, bridge and
+// subscription state rather than from counters.
+export {
+	FEC_INACTIVE_REASONS,
+	catalogDeclaresFec,
+	resolveFecState,
+	type FecActiveState,
+	type FecInactiveReason,
+	type FecInactiveState,
+	type FecState,
+	type FecStateEvidence,
+	type FecTransportPolicy,
+	type NoFecCounters,
+} from "./fec-state.js";
+
+export {
+	catalogAmtNetworkSource,
+	DEFAULT_AMT_RELAY_PORT,
+	type AmtNetworkSource,
+	type CatalogNetworkSource,
+} from "./catalog-network-source.js";
+
+// D-28 shared repair-fetch shell (per-SBN on-demand MoQ FEC repair backfill)
+export {
+  wireRepairFetch,
+  repairFetchSubscriberPriority,
+  SOURCE_MEDIA_PRIORITY_MAX,
+  type ResolveRepairTarget,
+  type RepairTarget,
+  type RepairFetchHost,
+  type RepairFetchPriority,
+  type RepairFetchRequest,
+  type RepairFetchTransport,
+  type RepairPriorityReason,
+  type RepairSkipReason,
+  type RepairSubscribeCallback,
+  type WireRepairFetchOptions,
+} from './repair-fetch.js'
+// MoQ repair group ids for iso-ssbg1-v1 blocks (BLO-35597): the 62-bit
+// wrap-epoch-extended SS_Start and the repair FETCH range for a lost SS_ID.
+export {
+  extSsStart,
+  extendSsId,
+  repairFetchRange,
+  type RepairFetchRange,
+} from '@blockcast/mmt-fec'
+export { DeliveryGapEstimator } from './delivery-gap.js'