/** @packageDocumentation MPEG (MP3) file format handler supporting ID3v1, ID3v2, and APE tags with audio property reading. */
import { ApeTag } from "../ape/apeTag.js";
import { File } from "../file.js";
import { Tag } from "../tag.js";
import type { IOStream } from "../toolkit/ioStream.js";
import { type offset_t, ReadStyle, StripTags } from "../toolkit/types.js";
import { ID3v1Tag } from "./id3v1/id3v1Tag.js";
import { Id3v2Tag } from "./id3v2/id3v2Tag.js";
import { MpegProperties } from "./mpegProperties.js";
/**
 * Bit-flag enum identifying which tag types are present in or should be
 * operated on within an MPEG file.
 */
export declare enum MpegTagTypes {
    /** No tags. */
    NoTags = 0,
    /** ID3v1 tag. */
    ID3v1 = 1,
    /** ID3v2 tag. */
    ID3v2 = 2,
    /** APE tag. */
    APE = 4,
    /** All supported tag types (bitwise OR of all members). */
    AllTags = 65535
}
/**
 * MPEG (MP3) file format handler.
 *
 * Supports ID3v1, ID3v2 and APE tags as well as MPEG / ADTS audio
 * property reading.
 */
export declare class MpegFile extends File {
    /** The ID3v2 tag, or `null` if not present. */
    private _id3v2Tag;
    /** The ID3v1 tag, or `null` if not present. */
    private _id3v1Tag;
    /** The APE tag, or `null` if not present. */
    private _apeTag;
    /** Priority-ordered combined tag that delegates to all present tag types. */
    private _combinedTag;
    /** Cached audio properties, or `null` if not read. */
    private _properties;
    /** Byte offset of the ID3v2 tag within the file, or `-1` if not present. */
    private _id3v2Location;
    /** Original byte size of the ID3v2 tag (used to calculate insertion deltas). */
    private _id3v2OriginalSize;
    /** Byte offset of the ID3v1 tag within the file, or `-1` if not present. */
    private _id3v1Location;
    /** Byte offset of the APE tag within the file, or `-1` if not present. */
    private _apeLocation;
    /** Original byte size of the APE tag (used to calculate insertion deltas). */
    private _apeOriginalSize;
    /**
     * Private constructor — use the static {@link MpegFile.open} factory method instead.
     * @param stream - The underlying I/O stream for this file.
     */
    private constructor();
    /**
     * Opens an MPEG file from the given stream, parsing tags and optionally audio properties.
     *
     * @param stream - The I/O stream to read from.
     * @param readProperties - Whether to read audio properties (default: `true`).
     * @param readStyle - The level of detail used when reading properties (default: `ReadStyle.Average`).
     * @returns A fully initialised `MpegFile` instance.
     */
    static open(stream: IOStream, readProperties?: boolean, readStyle?: ReadStyle): Promise<MpegFile>;
    /**
     * Returns the combined tag that delegates to all present tag types, in
     * priority order (ID3v2 > APE > ID3v1).
     *
     * @returns The combined tag instance.
     */
    tag(): Tag;
    /**
     * Returns the audio properties for this file, or `null` if they were not read.
     *
     * @returns The MPEG audio properties, or `null`.
     */
    audioProperties(): MpegProperties | null;
    /**
     * Saves the specified tag types to the file, optionally stripping tags not
     * included in the save mask.
     *
     * @param tags - Bit-flag indicating which tag types to save (default: {@link MpegTagTypes.AllTags}).
     * @param stripTags - Whether to strip tag types not present in `tags` (default: {@link StripTags.StripOthers}).
     * @returns `true` on success, `false` if the file is read-only.
     */
    save(tags?: MpegTagTypes, stripTags?: StripTags, version?: number): Promise<boolean>;
    /**
     * Returns `true` if the file contains a physical ID3v2 tag (i.e., one was
     * found during parsing or has been written by a previous {@link save} call).
     */
    get hasID3v2Tag(): boolean;
    /**
     * Returns `true` if the file contains a physical ID3v1 tag.
     */
    get hasID3v1Tag(): boolean;
    /**
     * Returns `true` if the file contains a physical APEv2 tag.
     */
    get hasAPETag(): boolean;
    /** Get the ID3v1 tag, optionally creating one if absent. */
    id3v1Tag(create?: boolean): ID3v1Tag | null;
    /** Get the ID3v2 tag, optionally creating one if absent. */
    id3v2Tag(create?: boolean): Id3v2Tag | null;
    /** Get the APE tag, optionally creating one if absent. */
    apeTag(create?: boolean): ApeTag | null;
    /**
     * Returns the byte offset of the first valid MPEG audio frame in the file.
     * Scanning begins after the ID3v2 tag (if present).
     *
     * @returns The file offset of the first frame, or `-1` if not found.
     */
    firstFrameOffset(): Promise<offset_t>;
    /**
     * Returns the byte offset of the last valid MPEG audio frame in the file.
     * Scanning ends before any trailing APE or ID3v1 tag.
     *
     * @returns The file offset of the last frame, or `-1` if not found.
     */
    lastFrameOffset(): Promise<offset_t>;
    /**
     * Scans forward from `position` and returns the offset of the next valid MPEG frame.
     *
     * @param position - The byte offset at which to start scanning.
     * @returns The file offset of the next valid frame, or `-1` if not found.
     */
    nextFrameOffset(position: offset_t): Promise<offset_t>;
    /**
     * Scans backward from `position` and returns the offset of the previous valid MPEG frame.
     *
     * @param position - The byte offset at which to start scanning (inclusive).
     * @returns The file offset of the previous valid frame, or `-1` if not found.
     */
    previousFrameOffset(position: offset_t): Promise<offset_t>;
    /**
     * Removes the specified tag types from the file.
     *
     * @param tags - Bit-flag indicating which tag types to strip (default: {@link MpegTagTypes.AllTags}).
     */
    strip(tags?: MpegTagTypes): Promise<void>;
    /**
     * Reads all tags and optionally audio properties from the stream.
     *
     * @param readProperties - Whether to read audio properties.
     * @param readStyle - The read-style detail level.
     */
    private read;
    /**
     * Scans the beginning of the file for an ID3v2 tag and populates
     * `_id3v2Tag`, `_id3v2Location`, and `_id3v2OriginalSize`.
     */
    private findID3v2;
    /**
     * Scans the end of the file for an ID3v1 tag and populates
     * `_id3v1Tag` and `_id3v1Location`.
     */
    private findID3v1;
    /**
     * Scans immediately before the ID3v1 tag (or end of file) for an APE tag and
     * populates `_apeTag`, `_apeLocation`, and `_apeOriginalSize`.
     */
    private findAPE;
    /**
     * Rebuilds the `_combinedTag` from the currently present tag objects,
     * maintaining priority order (ID3v2 > APE > ID3v1).
     */
    private refreshCombinedTag;
}
//# sourceMappingURL=mpegFile.d.ts.map