@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/index.ts

@@ -0,0 +1,443 @@
+/**
+ * @mmt/container - MMTP/LOC Container Parsing
+ *
+ * Shared container parsing library for MMT over MoQ and SSM.
+ *
+ * @packageDocumentation
+ */
+
+export type { AuthoredTiming } from './authored-timing.js'
+
+// MFU Reassembler
+export {
+  type MFUFragment,
+  type ReassembledMFU,
+  type ReassemblerStats,
+  type MFUReassemblerOptions,
+  type MfuReassemblerBackend,
+  type MmtpSourcePath,
+  MFUReassembler,
+  MfuReassemblyError,
+  type MfuReassemblyErrorCode,
+  createFragment,
+  processMMTPWithReassembly,
+} from './mfu-reassembler.js'
+
+// 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,
+  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,
+} from './codec-utils.js'
+
+// LOC FEC Extensions (draft-ramadan-moq-fec §7.1)
+export {
+  LOCHeaderExtensionId,
+  FEC_SBN_MAX,
+  FEC_ESI_MAX,
+  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,
+  isMulticastTrackObject,
+  isMulticastEndpoint,
+  isMulticastCatalogConfig,
+  type TrackTimingConfig,
+  isTrackTimingConfig,
+  resolveGroupDurationTicks,
+  resolveGroupDurationMs,
+  validateSwitchingSetTiming,
+  type CmsfCatalog,
+  type CmsfCatalogErrorCode,
+  CmsfCatalogValidationError,
+  validateCmsfMmtpCatalog,
+} 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,
+  buildAudioInitSegment,
+  generateGreenFillNAL,
+  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 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 WasmFecDecoder,
+  type FecStats,
+} from './fec-manager.js'
+
+// MMTP Router (packet processing + frame routing)
+export {
+  MmtpRouter,
+  KEYFRAME_LOST_TIMEOUT_SLACK,
+  type FrameCallback,
+  type FECManagerLike,
+  type MmtpIngressContext,
+  type RoutedPacketMeta,
+  type TrackPacketCallback,
+} from './mmtp-router.js'
+
+// MmtpContainerParser (unified, transport-agnostic)
+export {
+  MmtpContainerParser,
+  type MmtpParserConfig,
+  type MmtpParserRecord,
+  type TrackInfo,
+  type MmtpReorderStats,
+  type MmtpReorderFrameDiagnostics,
+  type MmtpReorderStreamDiagnostics,
+  type FrameMeta as ParserFrameMeta,
+  type PacketInfo,
+} 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 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,
+} from './multicast-manager.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,
+  type GroupDriftEvent,
+  type GroupBoundaryTicks,
+} 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,
+} 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,
+  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,
+} from "./catalog-fec-params.js";
+
+export {
+	catalogAmtNetworkSource,
+	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,
+  type ResolveRepairTarget,
+  type RepairFetchTransport,
+  type WireRepairFetchOptions,
+} from './repair-fetch.js'