/**
 * @packageDocumentation Abstract base class for audio file format implementations.
 *
 * Provides async I/O helpers that delegate to an {@link IOStream}, along with
 * metadata access via the format-specific {@link Tag} and
 * {@link AudioProperties} objects returned by the concrete subclass.
 */
import { ByteVector } from "./byteVector.js";
import { type offset_t, Position } from "./toolkit/types.js";
import { IOStream } from "./toolkit/ioStream.js";
import type { Tag } from "./tag.js";
import type { AudioProperties } from "./audioProperties.js";
import { PropertyMap } from "./toolkit/propertyMap.js";
import type { VariantMap } from "./toolkit/variant.js";
/**
 * Abstract base class for file format implementations. Provides common async
 * I/O helpers and delegates metadata access to the format-specific {@link Tag}
 * and {@link AudioProperties} objects.
 *
 * Concrete subclasses must implement {@link tag}, {@link audioProperties}, and
 * {@link save}.
 */
export declare abstract class File {
    /** The underlying I/O stream. */
    protected _stream: IOStream;
    /**
     * Whether the file was parsed successfully. Subclasses set this to `false`
     * when a fatal parse error is encountered.
     */
    protected _valid: boolean;
    /**
     * Constructs a `File` around the given stream.
     *
     * @param stream - The I/O stream to read from and write to.
     */
    constructor(stream: IOStream);
    /**
     * The name (path) of the underlying stream, as reported by the stream
     * itself. Synchronous.
     */
    get name(): string;
    /**
     * Returns the underlying {@link IOStream} used by this file.
     *
     * @returns The raw I/O stream.
     */
    stream(): IOStream;
    /**
     * Returns the format-specific tag, or `null` if unavailable.
     *
     * @returns The tag object, or `null`.
     */
    abstract tag(): Tag | null;
    /**
     * Returns the format-specific audio properties, or `null` if unavailable.
     *
     * @returns The audio properties object, or `null`.
     */
    abstract audioProperties(): AudioProperties | null;
    /**
     * Writes all pending tag and metadata changes back to the stream.
     *
     * @returns A promise that resolves to `true` on success, `false` on failure.
     */
    abstract save(): Promise<boolean>;
    /**
     * Returns a {@link PropertyMap} containing all tag fields exposed by this
     * file's tag. Returns an empty map if no tag is present.
     *
     * @returns The property map.
     */
    properties(): PropertyMap;
    /**
     * Replaces the tag's properties with the supplied map and returns a map of
     * properties that could not be set (unsupported keys).
     *
     * @param properties - The new property map to apply.
     * @returns A map of properties that were not applied.
     */
    setProperties(properties: PropertyMap): PropertyMap;
    /**
     * Removes unsupported properties from the tag.
     *
     * @param properties - The list of property keys to remove.
     */
    removeUnsupportedProperties(properties: string[]): void;
    /**
     * Returns the list of complex-property keys supported by the tag.
     *
     * @returns An array of key strings (e.g. `"PICTURE"`).
     */
    complexPropertyKeys(): string[];
    /**
     * Returns all complex property values for the given key.
     *
     * @param key - The complex property key.
     * @returns An array of {@link VariantMap} objects.
     */
    complexProperties(key: string): VariantMap[];
    /**
     * Sets complex property values for the given key.
     *
     * @param key - The complex property key.
     * @param value - The array of {@link VariantMap} objects to store.
     * @returns `true` if the property was set, `false` if not supported.
     */
    setComplexProperties(key: string, value: VariantMap[]): boolean;
    /**
     * Reads up to `length` bytes from the current stream position.
     *
     * @param length - The maximum number of bytes to read.
     * @returns A promise resolving to the bytes read as a {@link ByteVector}.
     */
    readBlock(length: number): Promise<ByteVector>;
    /**
     * Writes `data` at the current stream position.
     *
     * @param data - The bytes to write.
     * @returns A promise that resolves when the write is complete.
     */
    writeBlock(data: ByteVector): Promise<void>;
    /**
     * Inserts `data` into the stream at `start`, optionally replacing `replace`
     * bytes.
     *
     * @param data - The bytes to insert.
     * @param start - Byte offset at which to insert. Defaults to `0`.
     * @param replace - Number of bytes to overwrite. Defaults to `0`.
     * @returns A promise that resolves when the operation is complete.
     */
    insert(data: ByteVector, start?: offset_t, replace?: number): Promise<void>;
    /**
     * Removes `length` bytes from the stream starting at `start`.
     *
     * @param start - Byte offset of the first byte to remove. Defaults to `0`.
     * @param length - Number of bytes to remove. Defaults to `0`.
     * @returns A promise that resolves when the operation is complete.
     */
    removeBlock(start?: offset_t, length?: number): Promise<void>;
    /**
     * Whether the underlying stream is read-only. Synchronous.
     */
    get readOnly(): boolean;
    /**
     * Whether the underlying stream is currently open. Synchronous.
     */
    get isOpen(): boolean;
    /**
     * Whether this file was parsed successfully.
     */
    get isValid(): boolean;
    /**
     * Moves the stream's read/write cursor to `offset` relative to `position`.
     *
     * @param offset - The byte offset to seek to.
     * @param position - The seek origin. Defaults to {@link Position.Beginning}.
     * @returns A promise that resolves when the seek is complete.
     */
    seek(offset: offset_t, position?: Position): Promise<void>;
    /**
     * Resets the stream position to the beginning (equivalent to
     * `seek(0, Position.Beginning)`).
     *
     * @returns A promise that resolves when the operation is complete.
     */
    clear(): Promise<void>;
    /**
     * Returns the current byte offset of the stream cursor.
     *
     * @returns A promise resolving to the cursor position.
     */
    tell(): Promise<offset_t>;
    /**
     * Returns the total length of the stream in bytes.
     *
     * Note: this is an async method rather than a getter because getters cannot
     * be `async`.
     *
     * @returns A promise resolving to the stream length in bytes.
     */
    fileLength(): Promise<number>;
    /**
     * Truncates (or extends) the stream to exactly `length` bytes.
     *
     * @param length - The desired stream length in bytes.
     * @returns A promise that resolves when the truncation is complete.
     */
    truncate(length: offset_t): Promise<void>;
    /**
     * Searches the stream forward for `pattern` starting at `fromOffset`.
     *
     * The stream cursor is restored to its original position after the search.
     * If `before` is provided, the search stops (returning `-1`) as soon as
     * `before` is encountered.
     *
     * @param pattern - The byte sequence to search for.
     * @param fromOffset - Byte offset at which to start searching. Defaults to `0`.
     * @param before - Optional sentinel; if found before `pattern`, returns `-1`.
     * @returns A promise resolving to the byte offset of the first match, or
     *   `-1` if not found.
     */
    find(pattern: ByteVector, fromOffset?: offset_t, before?: ByteVector): Promise<offset_t>;
    /**
     * Searches the stream backward for `pattern`, starting at `fromOffset`
     * (default: end of file).
     *
     * The stream cursor is restored to its original position after the search.
     * If `before` is provided, the search stops (returning `-1`) as soon as
     * `before` is encountered while scanning backward.
     *
     * @param pattern - The byte sequence to search for.
     * @param fromOffset - Upper bound for the search. `0` means end of file.
     *   Defaults to `0`.
     * @param before - Optional sentinel; if found before `pattern`, returns `-1`.
     * @returns A promise resolving to the byte offset of the match, or `-1` if
     *   not found.
     */
    rfind(pattern: ByteVector, fromOffset?: offset_t, before?: ByteVector): Promise<offset_t>;
    /**
     * The size of the read buffer used by {@link find} and {@link rfind}, in
     * bytes.
     *
     * @returns The buffer size (1024).
     */
    static bufferSize(): number;
}
//# sourceMappingURL=file.d.ts.map