/** @packageDocumentation Abstract base class for OGG container file formats. Handles page-level I/O and logical packet reassembly. */
import { ByteVector } from "../byteVector.js";
import { File } from "../file.js";
import { IOStream } from "../toolkit/ioStream.js";
import { OggPageHeader } from "./oggPageHeader.js";
/**
 * Abstract base class for OGG-based file formats. Provides packet-level
 * access to the OGG bitstream by iterating pages and reassembling packets.
 *
 * On save, only header pages are re-rendered from packets. Audio pages are
 * preserved verbatim (with updated page sequence numbers) so that granule
 * positions, page boundaries, and audio data remain intact — producing
 * output that is fully seekable and playable.
 */
export declare abstract class OggFile extends File {
    /** Parsed page headers, or `null` if pages have not yet been read from the stream. */
    private _pages;
    /** Byte offset of each page within the stream, in page order. */
    private _pageOffsets;
    /** Raw bytes of each page, used for verbatim copying of audio pages during save. */
    private _pageRawData;
    /** Index of the first logical packet that begins on each page. */
    private _pageFirstPktIdx;
    /** Reassembled logical packets keyed by their zero-based packet index. */
    private _packets;
    /** Packets that have been modified in memory and not yet flushed to disk. */
    private _dirtyPackets;
    /** OGG serial number of the first (and only) logical bitstream encountered. */
    private _serialNumber;
    /**
     * Constructs an OggFile backed by the given stream.
     * @param stream - The I/O stream to read from and write to.
     */
    constructor(stream: IOStream);
    /**
     * Number of header packets for this OGG format.
     * Header packets are re-rendered on save; audio pages after them are
     * copied verbatim. Override in subclasses:
     * - Vorbis: 3 (identification, comment, setup)
     * - Opus/Speex/OGG FLAC: 2 (identification, comment)
     */
    protected get numHeaderPackets(): number;
    /**
     * Retrieve a logical packet by its zero-based index.
     * Returns the dirty (in-memory) version if one exists, otherwise reads and reassembles from disk.
     * @param index - Zero-based packet index.
     * @returns The packet data as a {@link ByteVector}.
     */
    packet(index: number): Promise<ByteVector>;
    /**
     * Mark a packet as dirty with new content to be written on the next save.
     * @param index - Zero-based packet index.
     * @param data - New packet data to store and use when saving.
     */
    setPacket(index: number, data: ByteVector): void;
    /**
     * Returns the header of the first OGG page in the stream.
     * @returns The first {@link OggPageHeader}, or `null` if the stream is empty or invalid.
     */
    firstPageHeader(): Promise<OggPageHeader | null>;
    /**
     * Returns the header of the last OGG page in the stream.
     * Used for computing total granule count and thus stream duration.
     * @returns The last {@link OggPageHeader}, or `null` if the stream is empty or invalid.
     */
    lastPageHeader(): Promise<OggPageHeader | null>;
    /**
     * Persist all pending packet changes to the underlying stream.
     *
     * Matches C++ `Ogg::File::writePacket` behaviour: for each dirty packet,
     * find the original pages that carry it, determine which other packets
     * co-reside on those pages, and repaginate only that range.  Unchanged
     * pages are copied verbatim (with adjusted sequence numbers).
     *
     * Key invariant: packet 0 (BOS/identification) always occupies exactly
     * one page by itself.  Non-BOS packets are repaginated with
     * `SinglePagePerGroup` when the combined segment count fits in one page
     * (≤ 255) or with `Repaginate` per packet otherwise — exactly mirroring
     * C++ `Ogg::Page::paginate`.
     *
     * @returns `true` on success, `false` if the file is read-only or has no pages.
     */
    save(): Promise<boolean>;
    /**
     * Parse all OGG pages from the stream and reassemble logical packets.
     * Results are cached; subsequent calls are no-ops until the cache is cleared (e.g., after save).
     */
    private readPages;
}
//# sourceMappingURL=oggFile.d.ts.map