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

package/dist/cmcd-producer.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/cmcd-producer.ts"],
+  "sourcesContent": ["/**\n * CmcdProducer \u2014 transport-agnostic CMCD telemetry producer.\n *\n * Maps FecTrackStats snapshots and TransportSnapshot state to x-bc-*\n * CMCD vendor keys (proto tags 70-99). Fires callbacks for two delivery\n * channels: MoQ SUBSCRIBE params and multicast HTTP POST.\n *\n * Does NOT call fetch() or write to QUIC directly \u2014 the player wiring\n * layer is responsible for attaching params to SUBSCRIBE or POSTing\n * the payload to the CDN CMCD endpoint.\n *\n * @see docs/superpowers/specs/2026-04-15-iwa-multicast-stack-design.md \u00A73.3\n * @see CDN+ Track D BLO-1044\n */\n\nimport type { FecTrackStats } from '@blockcast/fec-worker'\nimport type { ManifestVerificationStats } from '@blockcast/mmt-manifest-verify'\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Transport state snapshot, built by the player wiring layer from SocketPool. */\nexport interface TransportSnapshot {\n  transport: 'native' | 'amt' | 'moq'\n  /** IPv4/IPv6 multicast group address */\n  multicastGroup?: string\n  /** SSM source address */\n  multicastSource?: string\n  /** AMT relay address (omit when undefined) */\n  amtRelay?: string\n}\n\n/** Transport transition event identifiers for x-bc-ct. */\nexport type TransportTransitionEvent = 'mc-start' | 'mc-to-uc' | 'amt-start'\n\n/**\n * Phase 14 play-mode state (D-12, x-bc-play-mode):\n * - `full`         \u2014 base + delta both active\n * - `base-only`    \u2014 delta fell back; base carries playback\n * - `single-track` \u2014 stream is not a multi-track switching set (legacy)\n */\nexport type PlayMode = 'full' | 'base-only' | 'single-track'\n\nconst PLAY_MODES: readonly PlayMode[] = ['full', 'base-only', 'single-track']\n\n/** CMCD vendor key map. Values are string, number, or boolean. */\nexport type CmcdParams = Record<string, string | number | boolean>\n\n/** Options for CmcdProducer construction. */\nexport interface CmcdProducerOptions {\n  /** Fired on each snapshot and on transport transitions. Params for MoQ SUBSCRIBE. */\n  onCmcdParams?: (params: CmcdParams) => void\n  /** Fired on each snapshot and on transport transitions. RFC 9559 query-string for HTTP POST body. */\n  onCmcdPost?: (payload: string) => void\n}\n\n/** Snapshot data passed to onSnapshot(). */\nexport interface SnapshotData {\n  tracks: FecTrackStats[]\n  timestampMs: number\n}\n\n/** Transport-only telemetry for receivers that do not own FEC track stats. */\nexport interface TransportOnlySnapshotData {\n  transport: TransportSnapshot\n  timestampMs: number\n  playMode?: PlayMode\n  switchMiscount?: number\n}\n\n// ---------------------------------------------------------------------------\n// Value sanitization (T-06-01: header injection mitigation)\n// ---------------------------------------------------------------------------\n\n/** Strip commas, newlines, and carriage returns from string values. */\nfunction sanitize(value: string): string {\n  return value.replace(/[,\\r\\n]/g, '')\n}\n\n// ---------------------------------------------------------------------------\n// Key building (pure functions, no side effects)\n// ---------------------------------------------------------------------------\n\n/** Build FEC vendor keys from a FecTrackStats snapshot. */\nfunction buildFecParams(stats: FecTrackStats): CmcdParams {\n  const params: CmcdParams = {}\n  const cfg = stats.config\n\n  params['x-bc-fec-algo'] = cfg.algorithm\n  params['x-bc-fec-k'] = cfg.k\n  params['x-bc-fec-p'] = cfg.repairCount\n  params['x-bc-fec-recovery'] = parseFloat((stats.recoveryRate / 100).toFixed(4))\n\n  // Green-fill (symbol underrun) \u2014 omit when 0\n  if (stats.greenFillFrames > 0) {\n    params['x-bc-scu'] = stats.greenFillFrames\n  }\n\n  // ALTA keys: omit entirely when altaEnabled is false (D-09)\n  if (cfg.altaEnabled) {\n    params['x-bc-alta-verified'] = stats.altaVerified > 0\n    params['x-bc-alta-failures'] = stats.altaFailed\n  }\n\n  return params\n}\n\n/** Build transport vendor keys from a TransportSnapshot. */\nfunction buildTransportParams(snap: TransportSnapshot | undefined): CmcdParams {\n  if (!snap) return {}\n\n  const params: CmcdParams = {}\n  params['x-bc-transport'] = snap.transport\n\n  if (snap.multicastGroup != null) {\n    params['x-bc-multicast-group'] = snap.multicastGroup\n  }\n  if (snap.multicastSource != null) {\n    params['x-bc-multicast-source'] = snap.multicastSource\n  }\n  if (snap.amtRelay != null) {\n    params['x-bc-amt-relay'] = snap.amtRelay\n  }\n\n  return params\n}\n\n// ---------------------------------------------------------------------------\n// Query-string serialization (RFC 9559 \u00A72)\n// ---------------------------------------------------------------------------\n\n/**\n * Serialize CmcdParams to RFC 9559 query-string format.\n * Keys sorted for deterministic output. String values sanitized.\n */\nfunction formatQueryString(params: CmcdParams): string {\n  return Object.keys(params)\n    .sort()\n    .map(key => {\n      const v = params[key]\n      if (typeof v === 'string') return `${key}=${sanitize(v)}`\n      return `${key}=${v}`\n    })\n    .join(',')\n}\n\n// ---------------------------------------------------------------------------\n// CmcdProducer\n// ---------------------------------------------------------------------------\n\nexport class CmcdProducer {\n  #onCmcdParams: ((params: CmcdParams) => void) | undefined\n  #onCmcdPost: ((payload: string) => void) | undefined\n  #transport: TransportSnapshot | undefined\n  #lastStats: FecTrackStats | undefined\n  // Phase 14 state \u2014 Plan 03 Task 2 (D-12, D-15).\n  #playMode: PlayMode | null = null\n  #deltaFailRate: number | null = null\n  #switchMiscount = 0\n  #manifestStats: ManifestVerificationStats | null = null\n\n  constructor(options: CmcdProducerOptions) {\n    this.#onCmcdParams = options.onCmcdParams\n    this.#onCmcdPost = options.onCmcdPost\n  }\n\n  /** Update the stored transport state. Called by player wiring layer. */\n  updateTransport(snapshot: TransportSnapshot): void {\n    this.#transport = snapshot\n  }\n\n  /**\n   * Set the current play-mode. Emitted as `x-bc-play-mode` on subsequent\n   * snapshots. Throws on any value outside {'full','base-only','single-track'}\n   * (CLAUDE.md: error on bad init).\n   */\n  updatePlayMode(mode: PlayMode): void {\n    if (typeof mode !== 'string' || !PLAY_MODES.includes(mode as PlayMode)) {\n      throw new Error(\n        `[CmcdProducer] invalid play-mode \"${String(mode)}\"; expected one of: ${PLAY_MODES.join(', ')}`,\n      )\n    }\n    this.#playMode = mode\n  }\n\n  /**\n   * Set the delta-track FEC block-failure rate (0..1 inclusive). Emitted as\n   * `x-bc-delta-fail-rate` on snapshots when play-mode is 'full' or 'base-only'.\n   * Omitted on single-track streams.\n   */\n  updateDeltaFailRate(rate: number): void {\n    if (typeof rate !== 'number' || !Number.isFinite(rate) || rate < 0 || rate > 1) {\n      throw new Error(\n        `[CmcdProducer] invalid delta-fail-rate \"${String(rate)}\"; expected a finite number in [0, 1]`,\n      )\n    }\n    this.#deltaFailRate = rate\n  }\n\n  /**\n   * Bump the cumulative switching-set misalignment counter. Emitted as\n   * `x-bc-switch-miscount` on snapshots when the counter is > 0.\n   */\n  incrementSwitchMiscount(): void {\n    this.#switchMiscount += 1\n  }\n\n  updateManifestVerification(stats: ManifestVerificationStats): void {\n    this.#manifestStats = stats\n  }\n\n  /**\n   * One-shot emit of `x-bc-switch-drift-us` for a single misalignment event.\n   * Does NOT mutate snapshot state \u2014 subsequent onSnapshot() calls will not\n   * include the drift key until the next emitSwitchDrift(). Mirrors the\n   * existing onTransition() pattern.\n   */\n  emitSwitchDrift(driftUs: number): void {\n    if (\n      typeof driftUs !== 'number' ||\n      !Number.isFinite(driftUs) ||\n      driftUs < 0\n    ) {\n      throw new Error(\n        `[CmcdProducer] invalid drift-us \"${String(driftUs)}\"; expected a non-negative finite number`,\n      )\n    }\n    const params: CmcdParams = {}\n    if (this.#lastStats) Object.assign(params, buildFecParams(this.#lastStats))\n    Object.assign(params, buildTransportParams(this.#transport))\n    if (this.#switchMiscount > 0) params['x-bc-switch-miscount'] = this.#switchMiscount\n    params['x-bc-switch-drift-us'] = driftUs\n    this.#emit(params)\n  }\n\n  /**\n   * Process a FecTrackStats snapshot. Finds the video track, builds\n   * x-bc-* vendor keys, and fires both delivery callbacks.\n   */\n  onSnapshot(data: SnapshotData): void {\n    // Find first video track; skip if none\n    const videoTrack = data.tracks.find(t => t.config.trackType === 'video')\n    if (!videoTrack) return\n\n    this.#lastStats = videoTrack\n\n    const params: CmcdParams = {\n      ...buildFecParams(videoTrack),\n      ...buildTransportParams(this.#transport),\n    }\n\n    if (this.#playMode !== null) {\n      params['x-bc-play-mode'] = this.#playMode\n    }\n\n    // Delta-fail-rate is only meaningful when a delta track exists.\n    if (\n      this.#playMode !== null &&\n      this.#playMode !== 'single-track' &&\n      this.#deltaFailRate !== null\n    ) {\n      params['x-bc-delta-fail-rate'] = parseFloat(this.#deltaFailRate.toFixed(4))\n    }\n\n    if (this.#switchMiscount > 0) {\n      params['x-bc-switch-miscount'] = this.#switchMiscount\n    }\n    if (this.#manifestStats) {\n      params['x-bc-manifest-verified'] = this.#manifestStats.verified > 0\n      params['x-bc-manifest-failures'] = Object.values(this.#manifestStats.failures)\n        .reduce((total, count) => total + count, 0)\n    }\n\n    this.#emit(params)\n  }\n\n  /**\n   * Emit transport state without inventing FEC metrics. Cadence is owned by\n   * the caller because only the transport integration knows when state changed.\n   */\n  onTransportSnapshot(data: TransportOnlySnapshotData): void {\n    if (!Number.isFinite(data.timestampMs) || data.timestampMs < 0) {\n      throw new Error('[CmcdProducer] transport snapshot timestamp must be a non-negative finite number')\n    }\n    if (data.playMode !== undefined) this.updatePlayMode(data.playMode)\n    if (\n      data.switchMiscount !== undefined &&\n      (!Number.isSafeInteger(data.switchMiscount) || data.switchMiscount < 0)\n    ) {\n      throw new Error('[CmcdProducer] transport snapshot switch-miscount must be a non-negative safe integer')\n    }\n\n    this.#transport = data.transport\n    const params = buildTransportParams(data.transport)\n    if (this.#playMode !== null) params['x-bc-play-mode'] = this.#playMode\n    const switchMiscount = data.switchMiscount ?? this.#switchMiscount\n    if (switchMiscount > 0) params['x-bc-switch-miscount'] = switchMiscount\n    this.#emit(params)\n  }\n\n  /**\n   * Signal a transport transition event. Fires an immediate out-of-band\n   * emit with x-bc-ct set. The subsequent onSnapshot() will NOT include\n   * x-bc-ct (one-shot).\n   */\n  onTransition(event: TransportTransitionEvent): void {\n    const params: CmcdParams = {}\n\n    // Include last known FEC stats if available\n    if (this.#lastStats) {\n      Object.assign(params, buildFecParams(this.#lastStats))\n    }\n\n    // Include transport state if available\n    Object.assign(params, buildTransportParams(this.#transport))\n\n    // Add the transition event key (one-shot)\n    params['x-bc-ct'] = event\n\n    this.#emit(params)\n  }\n\n  /** Fire both delivery callbacks with the given params. */\n  #emit(params: CmcdParams): void {\n    this.#onCmcdParams?.(params)\n    this.#onCmcdPost?.(formatQueryString(params))\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/codec-utils.d.ts

@@ -0,0 +1,235 @@
+/**
+ * H.264/AVC codec utilities for MMTP container format conversion.
+ *
+ * Shared between moq-lib (hang-mmt-fec) and moqtail players.
+ * Handles AVCC↔Annex-B conversion, SPS/PPS extraction, fallback avcC generation,
+ * and MMTP timestamp conversion.
+ *
+ * @packageDocumentation
+ */
+/** Result of extracting a video codec configuration record from an fMP4 init segment. */
+export interface AvcCInfo {
+    codec: string;
+    description: Uint8Array;
+}
+/** Result of extracting AAC AudioSpecificConfig from an fMP4 init segment. */
+export interface AacAscInfo {
+    /** Codec string like "mp4a.40.2" (AAC-LC). Derived from AOT in ASC[0] >> 3. */
+    codec: string;
+    /** AudioSpecificConfig bytes — what AudioDecoder.configure({description}) needs for raw AAC. */
+    description: Uint8Array;
+}
+/** SPS and PPS NAL units extracted from an avcC record. */
+export interface SpsPps {
+    sps: Uint8Array;
+    pps: Uint8Array;
+}
+/** Options for fallback avcC generation. */
+export interface FallbackAvcCOptions {
+    /** Codec string like "avc1.640033". Profile/constraint/level parsed from hex triplet. */
+    codec?: string;
+    /** Coded width in pixels. Used in SPS pic_width_in_mbs. */
+    width?: number;
+    /** Coded height in pixels. Used in SPS pic_height_in_map_units. */
+    height?: number;
+}
+/**
+ * Extract the codec configuration record (avcC/hvcC/av1C/vpcC) from
+ * an fMP4 init segment (moov box).
+ * MMTP FT=0 packets contain a complete fMP4: moov > trak > mdia > minf > stbl > stsd > sample entry > codec config.
+ *
+ * Walks every trak and returns the first supported video sample entry. This
+ * handles both per-track CMSF init segments and multiplexed ftyp+moov blobs
+ * where the audio trak may appear before video.
+ */
+export declare function extractAvcCFromInitSegment(data: Uint8Array): AvcCInfo | undefined;
+/**
+ * Generate a minimal avcC (AVCDecoderConfigurationRecord) from codec parameters.
+ * Parses "avc1.XXYYZZ" → profile_idc=0xXX, constraint_flags=0xYY, level_idc=0xZZ.
+ * Width/height are encoded in the SPS; if not provided, they're inferred from the
+ * H.264 level's max frame size (e.g. level 4.2 → 2048x1088).
+ * Used when late MoQ subscribers miss the FT=0 init segment (moov/avcC).
+ */
+export declare function generateFallbackAvcC(options?: FallbackAvcCOptions | string): Uint8Array;
+/**
+ * Extract raw SPS and PPS NAL unit bytes from an avcC (AVCDecoderConfigurationRecord).
+ * Returns the first SPS and first PPS found.
+ */
+export declare function extractSpsPpsFromAvcC(avcC: Uint8Array): SpsPps | undefined;
+/**
+ * Convert AVCC (4-byte NAL length prefixed) to Annex-B (start code prefixed).
+ * Prepends SPS/PPS NALs before keyframes.
+ */
+export declare function avccToAnnexB(avccData: Uint8Array, isKeyframe: boolean, spsPps: SpsPps): Uint8Array;
+/**
+ * Build an avcC record by parsing Annex-B data to extract SPS (NAL type 7) and PPS (NAL type 8).
+ * Returns the avcC record, or null if SPS/PPS not found.
+ */
+export declare function extractCodecDescriptionFromAnnexB(data: Uint8Array): Uint8Array | null;
+/**
+ * Derive codec string from avcC record (e.g. "avc1.640033").
+ */
+export declare function codecStringFromAvcC(avcC: Uint8Array): string;
+/** VPS/SPS/PPS NAL units extracted from an HEVC keyframe (raw NAL bytes, no start code/length prefix). */
+export interface HevcParameterSets {
+    vps?: Uint8Array;
+    sps?: Uint8Array;
+    pps?: Uint8Array;
+}
+/** True for HEVC/H.265 codec strings (hev1.* / hvc1.*). */
+export declare function isHevcCodec(codec: string): boolean;
+/**
+ * Remove H.26x emulation-prevention bytes (0x03 after 0x00 0x00) from an RBSP so
+ * fixed-position fields (e.g. HEVC profile_tier_level) can be read by byte offset.
+ */
+export declare function removeEmulationPrevention(rbsp: Uint8Array): Uint8Array;
+/**
+ * Split an AVCC/hvcC bitstream (length-prefixed NAL units) into raw NAL byte slices.
+ * `lengthSize` is the NAL length prefix width (4 for FFmpeg LOC / fMP4 sample data).
+ */
+export declare function splitAvccNalUnits(data: Uint8Array, lengthSize?: number): Uint8Array[];
+/**
+ * True when `data` is exactly one or more length-prefixed NAL units.
+ *
+ * This is intentionally stricter than "starts with a plausible length": a
+ * H.264 AVCC access unit may begin with bytes `00 00 00 01` when the first
+ * NAL is a one-byte AUD. That byte pattern is also an Annex-B start code, so
+ * callers must prove the whole buffer is complete AVCC before falling back to
+ * Annex-B detection/conversion.
+ */
+export declare function isCompleteAvccSample(data: Uint8Array, lengthSize?: number): boolean;
+export type H264SampleFormat = 'avcc' | 'annexb' | 'raw-nal' | 'unknown';
+export type H264NalUnitFormat = H264SampleFormat | 'partial-avcc';
+export interface H264AvccSample {
+    data: Uint8Array;
+    format: H264SampleFormat;
+}
+export interface H264NalUnitSample {
+    nals: Uint8Array[];
+    format: H264NalUnitFormat;
+}
+/**
+ * Normalize a H.264 access unit/sample to length-prefixed AVCC for fMP4 mdat
+ * payloads. Already-AVCC samples are returned as-is. Annex-B and single raw
+ * NAL samples are converted one-way to AVCC at the MSE/fMP4 boundary.
+ */
+export declare function normalizeH264SampleToAvcc(data: Uint8Array): H264AvccSample;
+/**
+ * Split a H.264 access unit/sample into NAL units without changing its framing.
+ * Use this for routing, keyframe gates, and diagnostics. Conversion to AVCC is
+ * reserved for `normalizeH264SampleToAvcc` at the fMP4/MSE boundary.
+ */
+export declare function splitH264SampleNalUnits(data: Uint8Array, options?: H264KeyframeDetectionOptions): H264NalUnitSample;
+/**
+ * Extract HEVC VPS (type 32) / SPS (33) / PPS (34) NAL units from a keyframe access
+ * unit. Accepts either Annex-B (start-code delimited) or AVCC/hvcC (length-prefixed)
+ * framing — FFmpeg LOC delivers the latter.
+ */
+export declare function extractHevcParameterSets(keyframe: Uint8Array): HevcParameterSets;
+/**
+ * Build a minimal hvcC (HEVCDecoderConfigurationRecord, ISO 14496-15 §8.3.3.1) from
+ * VPS/SPS/PPS NAL units. The general profile_tier_level (12 bytes) is copied from the
+ * SPS (de-emulated); remaining fields use the common 4:2:0 / 8-bit / 4-byte-NAL-length
+ * defaults. Suitable as the `description` for a WebCodecs hvc1 VideoDecoderConfig.
+ *
+ * WebCodecs REQUIRES a description for length-prefixed HEVC — unlike H.264, Chrome will
+ * not self-configure HEVC from the bitstream (BLO-7764).
+ */
+export declare function generateHvcCFromParameterSets(sets: HevcParameterSets): Uint8Array | null;
+/**
+ * Build an hvcC `description` for a WebCodecs HEVC VideoDecoderConfig directly from a
+ * keyframe access unit (Annex-B or length-prefixed). Returns null if VPS/SPS/PPS aren't
+ * present in-band. HEVC analogue of {@link extractCodecDescriptionFromAnnexB}.
+ */
+export declare function extractHevcCodecDescription(keyframe: Uint8Array): Uint8Array | null;
+/**
+ * Strip non-VCL NAL units (VPS/SPS/PPS/SEI/AUD, type >= 32) from an HEVC access unit,
+ * returning only the VCL NAL units (type <= 31) as a 4-byte length-prefixed buffer.
+ *
+ * Required when decoding `hvc1` with an explicit hvcC `description`: WebCodecs rejects a
+ * sample whose data still carries in-band parameter sets ("Unable to determine size of
+ * bitstream buffer"). Accepts Annex-B or length-prefixed input. Returns the input
+ * unchanged if it already contains only VCL NALs (cheap no-op for delta frames).
+ */
+export declare function hevcVclOnly(data: Uint8Array): Uint8Array;
+/**
+ * Check if data starts with an Annex-B start code (00 00 01 or 00 00 00 01).
+ */
+export declare function isAnnexB(data: Uint8Array): boolean;
+/**
+ * Find the byte offset of the first Annex-B start code in data.
+ * Returns -1 if no start code found.
+ */
+export declare function findAnnexBStartCode(data: Uint8Array): number;
+/**
+ * Split Annex-B bitstream into NAL units.
+ * Returns array of NAL unit byte slices (without start codes).
+ */
+export declare function splitAnnexBNalUnits(data: Uint8Array): Uint8Array[];
+/**
+ * Convert Annex-B (start-code delimited) to AVCC (4-byte length prefixed).
+ * Optionally prepends SPS/PPS NALs for keyframes.
+ */
+export declare function annexBToAvcc(data: Uint8Array, spsPps?: SpsPps): Uint8Array;
+export interface H264KeyframeDetectionOptions {
+    /**
+     * Allow classifying a length-prefixed NAL when the declared NAL length runs
+     * beyond this buffer. MMTP routing can see only the first packet fragment of
+     * a sample, where the NAL header is present but the full NAL is not.
+     */
+    allowPartialAvcc?: boolean;
+}
+/**
+ * Classify H.264 keyframe status by scanning NAL units. Returns undefined when
+ * the payload is not H.264-classifiable. Handles Annex-B and AVCC formats.
+ */
+export declare function classifyH264Keyframe(data: Uint8Array, options?: H264KeyframeDetectionOptions): boolean | undefined;
+/**
+ * Detect H.264 keyframe by scanning for IDR/SPS or intra non-IDR slices.
+ * Handles both Annex-B and AVCC formats.
+ */
+export declare function detectH264Keyframe(data: Uint8Array, options?: H264KeyframeDetectionOptions): boolean;
+/**
+ * Convert MMTP timestamp (NTP short format) to monotonic microseconds.
+ * Per ISO 23008-1 §9.2.2 / RFC 5905: upper 16 bits = seconds (lower 16
+ * of NTP seconds), lower 16 bits = fractional seconds.
+ * Returns a monotonically increasing µs value within an ~18-hour window.
+ */
+export declare function mmtpTimestampToMicros(rawTs: bigint | number): number;
+/** Validate the CMSF/MMTP catalog initData contract: complete top-level ftyp+moov. */
+export declare function isFmp4InitSegment(data: Uint8Array): boolean;
+/**
+ * Prepend a 7-byte ADTS header to a raw AAC access unit.
+ *
+ * WebCodecs AudioDecoder configured WITHOUT an AudioSpecificConfig `description`
+ * expects ADTS-framed AAC.  MMTP carries raw AAC (no ADTS sync), so this wrapper
+ * must be applied before calling `AudioDecoder.decode()`.
+ */
+export declare function wrapAdtsFrame(raw: Uint8Array, sampleRate: number, channels: number): Uint8Array;
+/**
+ * Extract AAC AudioSpecificConfig (ASC) from an fMP4 init segment.
+ *
+ * Walks moov > trak > mdia > minf > stbl > stsd > mp4a > esds, then descends
+ * the MPEG-4 descriptor chain (ES_Descriptor 0x03 > DecoderConfigDescriptor
+ * 0x04 > DecoderSpecificInfo 0x05) to return the ASC payload.
+ *
+ * Sibling of extractAvcCFromInitSegment, used by the same BLO-4830 / CMSF §3.1
+ * path: when the catalog initData is the full ftyp+moov, WebCodecs' AudioDecoder
+ * needs the raw ASC (~2 bytes for AAC-LC) as `description`, NOT the whole
+ * segment. Without this extraction the configure() succeeds but every decode()
+ * silently produces zero output (no error fires), exactly the symptom that
+ * shows up as "Audio continuity FAILED: energy unstable CV=1.00" in the
+ * 7-point E2E test (CV=1.00 is the meanEnergy=0 sentinel from audio-fft.mjs).
+ *
+ * Returns undefined when:
+ *  - data has no ftyp/moov magic in the first 32 bytes
+ *  - no mp4a sample entry exists in any trak's stbl
+ *  - the esds descriptor chain doesn't yield a DecoderSpecificInfo
+ *  - the ASC payload is shorter than 2 bytes (AOT + sampling-freq nibble)
+ *
+ * Walks every trak and returns the first AAC sample entry. This mirrors
+ * extractAvcCFromInitSegment so multiplexed ftyp+moov init blobs work
+ * regardless of track order.
+ */
+export declare function extractAacAscFromInitSegment(data: Uint8Array): AacAscInfo | undefined;
+//# sourceMappingURL=codec-utils.d.ts.map

package/dist/codec-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-utils.d.ts","sourceRoot":"","sources":["../src/codec-utils.ts"],"names":[],"mappings":"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"}