import type { Nullable } from "../types/index.js";
/**
 * Represents a complete MP4 box with its type and data.
 */
export interface MP4Box {
    data: Buffer;
    size: number;
    type: string;
}
/**
 * Callback invoked when a complete box is parsed.
 */
export type MP4BoxCallback = (box: MP4Box) => void;
/**
 * MP4 box parser that handles streaming input.
 */
export interface MP4BoxParser {
    flush: () => void;
    push: (chunk: Buffer) => void;
}
/**
 * Creates an MP4 box parser that processes streaming input. The parser buffers incomplete boxes and invokes the callback when a complete box is available.
 * @param onBox - Callback invoked for each complete box.
 * @returns The parser interface with push and flush methods.
 */
export declare function createMP4BoxParser(onBox: MP4BoxCallback): MP4BoxParser;
/**
 * Iterates over the immediate child boxes within a container box's payload. Container boxes in ISO 14496-12 (moof, traf, etc.) contain a sequence of child boxes
 * starting immediately after the parent's 8-byte header. This function parses each child box header and invokes the callback with the child's type, the parent buffer,
 * and the byte offset/size of the child box within that buffer. The callback receives offsets rather than sub-buffers to avoid memory allocation in the hot path.
 * @param data - The complete parent box buffer including its own 8-byte header.
 * @param callback - Called for each child box with (type, data, offset, size). The offset and size describe the child box's position within data.
 */
export declare function iterateChildBoxes(data: Buffer, callback: (type: string, data: Buffer, offset: number, size: number) => void): void;
/**
 * Detects whether a moof box starts with a keyframe (sync sample) by examining the sample flags of the first sample in each trun box. The detection inspects all traf
 * boxes within the moof to handle multi-track containers (e.g., separate audio and video tracks). A non-keyframe signal from any traf (sample_depends_on === 2) takes
 * precedence because audio tracks are always independently decodable — the only source of sample_depends_on === 2 is a non-keyframe video track. This avoids needing
 * to map track IDs back to the moov box's codec metadata.
 *
 * The function checks three flag sources in priority order per the ISO 14496-12 spec: trun first_sample_flags (0x004), trun per-sample flags (0x400), and tfhd
 * default_sample_flags (0x020).
 *
 * @param moofData - The complete moof box buffer including its 8-byte header.
 * @returns true if the moof starts with a keyframe, false if it starts with a non-keyframe, or null if the flags could not be determined.
 */
export declare function detectMoofKeyframe(moofData: Buffer): Nullable<boolean>;
/**
 * Per-track result from offset-based timestamp rewriting. The caller uses these values to initialize offsets lazily and to track the "next expected" timestamp for
 * future tab replacement handoff.
 */
export interface OffsetTrackResult {
    duration: bigint;
    originalTfdt: bigint;
}
/**
 * Applies a constant per-track offset to Chrome's original tfdt.baseMediaDecodeTime values. Reads Chrome's original tfdt, adds the per-track offset, and writes back.
 * During normal playback the offset is 0 (pure pass-through of Chrome's wall-clock-based timestamps). At tab replacement boundaries the offset bridges the PTS
 * discontinuity — it is computed once per track from the difference between the previous segmenter's "next expected" value and Chrome's new starting tfdt.
 *
 * This approach preserves Chrome's inter-track synchronization. Chrome uses wall-clock-based timestamps that keep audio and video aligned regardless of frame drops.
 *
 * The rewrite is done in-place on the moof buffer. This is safe because the buffer is an owned copy created by the MP4 box parser (Buffer.from() in
 * createMP4BoxParser).
 *
 * @param moofData - The complete moof box buffer including its 8-byte header. Modified in place.
 * @param trackOffsets - Map from track_ID to the constant offset (in timescale units) to add to Chrome's original tfdt. Entries may be absent for tracks whose
 * offsets have not been initialized yet — the caller initializes them lazily from the returned originalTfdt values.
 * @returns Map from track_ID to { originalTfdt, duration }. The caller uses originalTfdt for lazy offset initialization and duration for EXTINF and "next expected"
 * tracking. Each entry corresponds to one traf box in the moof.
 */
export declare function offsetMoofTimestamps(moofData: Buffer, trackOffsets: Map<number, bigint>): Map<number, OffsetTrackResult>;
/**
 * Extracts per-track timescale values from a moov (movie header) box. Each track in the moov contains a tkhd box with the track_ID and an mdia > mdhd box with the
 * timescale. The timescale converts sample durations (in timescale units) to real seconds: seconds = duration / timescale. For example, a timescale of 16000 means
 * each unit is 1/16000 of a second.
 *
 * Parsing path: moov > trak > { tkhd (track_ID), mdia > mdhd (timescale) }
 *
 * @param moovData - The complete moov box buffer including its 8-byte header.
 * @returns Map from track_ID to timescale. Empty if no valid tracks are found.
 */
export declare function parseMoovTimescales(moovData: Buffer): Map<number, number>;