/** @packageDocumentation Matroska/WebM file format handler. */
import { File } from "../file.js";
import { IOStream } from "../toolkit/ioStream.js";
import { ReadStyle } from "../toolkit/types.js";
import { PropertyMap } from "../toolkit/propertyMap.js";
import type { VariantMap } from "../toolkit/variant.js";
import { MatroskaTag } from "./matroskaTag.js";
import { MatroskaProperties } from "./matroskaProperties.js";
/**
 * An implementation of TagLib::File for Matroska containers
 * (MKV, MKA, WebM).
 */
export declare class MatroskaFile extends File {
    /** The Matroska tag for this file, or `null` if not yet parsed. */
    private _tag;
    /** Audio properties for this file, or `null` if not yet parsed. */
    private _properties;
    /** Read style used during parsing, retained for lazy property construction. */
    private _readStyle;
    /** The parsed Tags EBML element, or `null` if absent. */
    private _tagsEl;
    /** The parsed Attachments EBML element, or `null` if absent. */
    private _attachmentsEl;
    /** Byte offset of the segment size VINT, or -1 if unknown. */
    private _segmentSizeVintOffset;
    /** Byte length of the segment size VINT encoding. */
    private _segmentSizeVintLength;
    /** Absolute byte offset of the segment data start (after Segment ID + size VINT). */
    private _segmentDataOffset;
    /**
     * The SeekHead element parsed from the file, or `null` if absent.
     * Used to add new SeekEntries when Tags/Attachments are appended.
     */
    private _seekHeadEl;
    /**
     * The Void element that immediately follows the SeekHead (pre-allocated padding),
     * or `null` if absent.  This space is available for expanding the SeekHead.
     */
    private _voidAfterSeekHeadEl;
    /**
     * Private constructor — use {@link MatroskaFile.open} instead.
     * @param stream - The underlying I/O stream.
     * @param readStyle - Detail level for audio property parsing.
     */
    private constructor();
    /**
     * Open and parse a Matroska file.
     * @param stream - The I/O stream to read from.
     * @param readProperties - Whether to parse audio properties.
     * @param readStyle - Detail level for audio property parsing.
     * @returns A fully initialized {@link MatroskaFile} instance.
     */
    static open(stream: IOStream, readProperties?: boolean, readStyle?: ReadStyle): Promise<MatroskaFile>;
    /** Returns the Matroska tag, or `null` if not present. */
    tag(): MatroskaTag | null;
    /** Returns the audio properties, or `null` if not parsed. */
    audioProperties(): MatroskaProperties | null;
    /**
     * Write the current tag and attachments back to the file.
     * @returns `true` on success, `false` if the file is read-only or invalid.
     */
    save(): Promise<boolean>;
    /**
     * Replace an existing EBML element with new data, or insert at end of segment.
     * Uses Void elements to fill any leftover space if the new data is smaller.
     */
    private replaceOrInsertElement;
    /**
     * Render a Void element using the same size-VINT strategy as C++ TagLib's
     * VoidElement::renderSize(): sizeLength = min(totalSize - 1, 8), meaning
     * large Voids always use an 8-byte size VINT (matching the on-disk format).
     */
    private renderTaglibCompatVoidElement;
    /**
     * Update the SeekHead in-place to include (or replace) an entry for the given
     * element ID at the given segment-relative offset.  Uses the Void element
     * immediately after the SeekHead as padding buffer.  If the new SeekHead would
     * exceed the combined SeekHead + Void space, the update is silently skipped.
     */
    private updateSeekHeadEntry;
    /**
     * Append data at the end of the segment.
     * Updates the segment size VINT to the exact new size (matching C++ TagLib's
     * Segment::render() which uses renderVINT(newDataSize, sizeLength)).
     * Also updates the SeekHead to include the new element's position.
     */
    private appendAtEndOfSegment;
    /** Returns the tag's PropertyMap, or an empty map if no tag exists. */
    properties(): PropertyMap;
    /**
     * Set tag properties from a PropertyMap.
     * @param properties - The properties to apply.
     * @returns A map of properties that could not be set.
     */
    setProperties(properties: PropertyMap): PropertyMap;
    /**
     * Remove unsupported properties from the tag.
     * @param properties - Property keys to remove.
     */
    removeUnsupportedProperties(properties: string[]): void;
    /** Returns the list of supported complex property keys (e.g. `"PICTURE"`). */
    complexPropertyKeys(): string[];
    /**
     * Returns complex property values for the given key.
     * @param key - The complex property key (e.g. `"PICTURE"`).
     * @returns An array of variant maps, one per complex property value.
     */
    complexProperties(key: string): VariantMap[];
    /**
     * Set complex property values for the given key.
     * @param key - The complex property key (e.g. `"PICTURE"`).
     * @param value - An array of variant maps to set.
     * @returns `true` if the key was handled, `false` otherwise.
     */
    setComplexProperties(key: string, value: VariantMap[]): boolean;
    /**
     * Parse the EBML/Matroska structure from the stream.
     * @param readProperties - Whether to parse audio properties.
     * @param readStyle - Detail level for audio property parsing.
     */
    private read;
    /**
     * Parse a SeekHead element and populate `positions` with element ID → absolute offset.
     * @param segmentDataOffset - Absolute byte offset of the segment data start.
     * @param seekHeadEl - The SeekHead EBML element to parse.
     * @param positions - Map to populate with element ID → file offset entries.
     */
    private parseSeekHead;
    /**
     * Parse a single Seek entry and add the resolved absolute offset to `positions`.
     * @param segmentDataOffset - Absolute byte offset of the segment data start.
     * @param seekEl - The Seek EBML element to parse.
     * @param positions - Map to update with element ID → file offset.
     */
    private parseSeekEntry;
    /**
     * Parse the Segment Info element and update audio properties with duration and title.
     * @param infoEl - The Info EBML element to parse.
     * @param readProperties - Whether to populate audio properties.
     */
    private parseInfo;
    /**
     * Parse the Tracks element to locate the first audio track.
     * @param tracksEl - The Tracks EBML element to parse.
     */
    private parseTracks;
    /**
     * Parse a single TrackEntry element and extract audio codec information.
     * @param trackEntryEl - The TrackEntry EBML element to parse.
     * @param audioAlreadyFound - Whether an audio track has already been processed.
     */
    private parseTrackEntry;
    /**
     * Parse the Audio sub-element of a TrackEntry and populate sample rate,
     * channel count, and bit depth on the audio properties.
     * @param audioEl - The Audio EBML element to parse.
     */
    private parseAudioElement;
}
//# sourceMappingURL=matroskaFile.d.ts.map