/** @packageDocumentation FileRef — format-agnostic entry point for opening audio files and accessing their tags and properties. */
import { File } from "./file.js";
import { Tag } from "./tag.js";
import { AudioProperties } from "./audioProperties.js";
import { IOStream } from "./toolkit/ioStream.js";
import { PropertyMap } from "./toolkit/propertyMap.js";
import { ReadStyle } from "./toolkit/types.js";
import type { VariantMap } from "./toolkit/variant.js";
/**
 * Format-agnostic handle for an audio file.
 *
 * `FileRef` detects the audio format automatically (by file-name extension
 * first, then by magic-byte content inspection) and instantiates the correct
 * format-specific {@link File} subclass. All common tag and audio-property
 * operations are exposed as convenience methods so that callers rarely need to
 * interact with the underlying {@link File} directly.
 *
 * @example
 * Open an audio file from a browser `File` object
 * ```ts
 * const ref = await FileRef.fromBlob(file, file.name);
 * if (ref.isValid) {
 *   console.log(ref.tag()?.title);
 * }
 * ```
 */
export declare class FileRef {
    /** The underlying format-specific file instance, or `null` if detection failed. */
    private _file;
    /** @param file The resolved format-specific file, or `null`. */
    private constructor();
    /**
     * Open an audio stream and return a `FileRef`.
     *
     * @param stream           The audio data stream.
     * @param readProperties   When `true` (default), audio properties are parsed.
     * @param readStyle        Controls parsing accuracy vs. performance.
     * @returns A `FileRef` whose {@link isValid} reflects whether the format was
     *          recognised and parsed successfully.
     */
    static open(stream: IOStream, readProperties?: boolean, readStyle?: ReadStyle): Promise<FileRef>;
    /**
     * Create a `FileRef` from a raw byte array.
     *
     * @param data             The audio data.
     * @param filename         Optional filename used for extension-based format
     *                         detection (e.g. `"track.mp3"`). Falls back to
     *                         content-based detection when empty.
     * @param readProperties   When `true` (default), audio properties are parsed.
     * @param readStyle        Controls parsing accuracy vs. performance.
     * @returns A resolved `FileRef`.
     */
    static fromByteArray(data: Uint8Array, filename?: string, readProperties?: boolean, readStyle?: ReadStyle): Promise<FileRef>;
    /**
     * Create a `FileRef` from a browser `Blob` or `File`.
     *
     * @param blob             The blob containing audio data.
     * @param filename         Optional filename override for extension-based
     *                         detection. When omitted and `blob` is a `File`,
     *                         `blob.name` is used automatically.
     * @param readProperties   When `true` (default), audio properties are parsed.
     * @param readStyle        Controls parsing accuracy vs. performance.
     * @returns A resolved `FileRef`.
     */
    static fromBlob(blob: Blob, filename?: string, readProperties?: boolean, readStyle?: ReadStyle): Promise<FileRef>;
    /** The tag exposed by the underlying file, or `null` if unavailable. */
    tag(): Tag | null;
    /** The audio properties exposed by the underlying file, or `null` if unavailable. */
    audioProperties(): AudioProperties | null;
    /** The underlying format-specific file instance, or `null`. */
    file(): File | null;
    /** `true` when no format was detected or the file could not be parsed. */
    get isNull(): boolean;
    /** `true` when the file was detected and parsed without errors. */
    get isValid(): boolean;
    /**
     * Write any pending tag changes back to the in-memory stream.
     *
     * @returns `true` on success, `false` if saving failed or no file is open.
     */
    save(): Promise<boolean>;
    /**
     * Return all tag fields as a unified {@link PropertyMap}.
     * Returns an empty map when no file is open.
     */
    properties(): PropertyMap;
    /**
     * Apply a {@link PropertyMap} to the underlying tag.
     *
     * @param props The properties to set.
     * @returns Unsupported properties, or `props` unchanged when no file is open.
     */
    setProperties(props: PropertyMap): PropertyMap;
    /**
     * Remove properties not supported by the underlying tag format.
     *
     * @param props Keys of the properties to remove.
     */
    removeUnsupportedProperties(props: string[]): void;
    /**
     * Return the keys of all complex (non-string) properties stored in the file.
     *
     * @returns An array of property key strings, or `[]` when no file is open.
     */
    complexPropertyKeys(): string[];
    /**
     * Return all complex property values for the given key.
     *
     * @param key The property key (e.g. `"PICTURE"`).
     * @returns An array of {@link VariantMap} objects, or `[]` when no file is open.
     */
    complexProperties(key: string): VariantMap[];
    /**
     * Set complex property values for the given key.
     *
     * @param key   The property key (e.g. `"PICTURE"`).
     * @param value The new values to store.
     * @returns `true` if stored, `false` if the format does not support this or no file is open.
     */
    setComplexProperties(key: string, value: VariantMap[]): boolean;
    /**
     * Return the list of file extensions recognized by taglib-ts.
     *
     * @returns An array of lowercase extension strings (without the leading dot).
     */
    static defaultFileExtensions(): string[];
    /**
     * Detect the format for `stream` and return the resolved format key,
     * or `null` when the format is not recognised.
     *
     * @param stream         The audio data stream.
     * @param readProperties Whether to parse audio properties.
     * @param readStyle      Parsing accuracy vs. performance trade-off.
     * @returns The underlying {@link File} instance, or `null`.
     */
    private static createFile;
    /**
     * Dynamically import and instantiate the correct format-specific file class.
     *
     * @param format         The format key returned by the detection functions.
     * @param stream         The audio data stream.
     * @param readProperties Whether to parse audio properties.
     * @param readStyle      Parsing accuracy vs. performance trade-off.
     * @returns The instantiated {@link File}, or `null` if the format is unknown
     *          or if the dynamic import fails.
     */
    private static instantiateFormat;
}
//# sourceMappingURL=fileRef.d.ts.map