/** @packageDocumentation APEv2 tag implementation, including item, footer, and tag classes. */
import { ByteVector } from "../byteVector.js";
import { Tag } from "../tag.js";
import { PropertyMap } from "../toolkit/propertyMap.js";
import type { IOStream } from "../toolkit/ioStream.js";
import type { offset_t } from "../toolkit/types.js";
/** Value type for an APE tag item. */
export declare enum ApeItemType {
    /** Item contains one or more UTF-8 text strings separated by null bytes. */
    Text = 0,
    /** Item contains raw binary data. */
    Binary = 1,
    /** Item contains a URI locator string. */
    Locator = 2
}
/**
 * A single APE tag item.
 *
 * Binary layout:
 *   valueLength(4 LE) + flags(4 LE) + key(null-terminated ASCII) + value
 */
export declare class ApeItem {
    /** Case-sensitive ASCII key identifying this item. */
    key: string;
    /** Decoded text values (for Text/Locator items). */
    values: string[];
    /** Data type of this item's value. */
    type: ApeItemType;
    /** Whether this item is marked read-only in the tag. */
    readOnly: boolean;
    /** Raw binary payload (for Binary items). */
    binaryData: ByteVector;
    /**
     * Parse one APE item starting at `offset` in `data`.
     * Returns the parsed item and how many bytes were consumed, or null on error.
     */
    static parse(data: ByteVector, offset: number): {
        item: ApeItem;
        bytesUsed: number;
    } | null;
    /**
     * Render this item to bytes.
     */
    render(): ByteVector;
    /** Returns a human-readable representation of this item's value. */
    toString(): string;
}
/**
 * 32-byte APE tag footer (or header).
 *
 * Layout:
 *   "APETAGEX"(8) + version(4 LE) + tagSize(4 LE) +
 *   itemCount(4 LE) + flags(4 LE) + reserved(8 zeros)
 */
export declare class ApeFooter {
    /** APEv2 format version (e.g. 2000 for APEv2). */
    version: number;
    /** Size in bytes of the tag data, including the footer but excluding the header. */
    tagSize: number;
    /** Number of items stored in this tag. */
    itemCount: number;
    /** Bit-field of tag flags (header presence, read-only, etc.). */
    flags: number;
    static readonly SIZE = 32;
    static readonly FILE_IDENTIFIER: ByteVector;
    /** `true` if this 32-byte block represents a header rather than a footer. */
    get isHeader(): boolean;
    /** `true` if a 32-byte header precedes the tag items in the stream. */
    get hasHeader(): boolean;
    /** Total tag size including header (if present), items, and footer. */
    get completeTagSize(): number;
    /**
     * Parse a 32-byte block as an APE footer/header.
     */
    static parse(data: ByteVector): ApeFooter | null;
    /**
     * Render as a 32-byte footer block.
     */
    render(): ByteVector;
    /**
     * Render as a 32-byte header block.
     */
    renderHeader(): ByteVector;
    /**
     * Render this footer/header block with the given flag overrides.
     *
     * @param flagsValue - The flags field to encode in the output block.
     * @returns A 32-byte `ByteVector`.
     */
    private renderBlock;
}
/**
 * APE (APEv2) tag implementation.
 */
export declare class ApeTag extends Tag {
    /** Internal list of all APE items in tag order. */
    private _items;
    /** Track title stored in the "TITLE" item. */
    get title(): string;
    /** @param v - New title string; empty string removes the item. */
    set title(v: string);
    /** Lead artist/performer stored in the "ARTIST" item. */
    get artist(): string;
    /** @param v - New artist string; empty string removes the item. */
    set artist(v: string);
    /** Album title stored in the "ALBUM" item. */
    get album(): string;
    /** @param v - New album string; empty string removes the item. */
    set album(v: string);
    /** User comment stored in the "COMMENT" item. */
    get comment(): string;
    /** @param v - New comment string; empty string removes the item. */
    set comment(v: string);
    /** Genre stored in the "GENRE" item. */
    get genre(): string;
    /** @param v - New genre string; empty string removes the item. */
    set genre(v: string);
    /**
     * Release year, read from the "YEAR" item (falling back to "DATE").
     * Returns `0` when not set.
     */
    get year(): number;
    /**
     * @param v - Four-digit year, or `0` to remove the item.
     * Any pre-existing "DATE" alias item is also removed.
     */
    set year(v: number);
    /**
     * Track number, read from the "TRACK" item (falling back to "TRACKNUMBER").
     * Returns `0` when not set.
     */
    get track(): number;
    /**
     * @param v - Track number, or `0` to remove the item.
     * Any pre-existing "TRACKNUMBER" alias item is also removed.
     */
    set track(v: number);
    /** An APE tag is empty when it contains no items. */
    get isEmpty(): boolean;
    /**
     * Asynchronously read an APE tag from the given stream. `offset` points to
     * the start of the 32-byte footer. Returns a `Promise<ApeTag>`.
     *
     * @param stream - The stream to read from.
     * @param offset - Byte offset of the 32-byte APE footer within `stream`.
     * @returns A resolved promise containing the populated tag (may be empty on
     *   parse failure).
     */
    static readFrom(stream: IOStream, offset: offset_t): Promise<ApeTag>;
    /** A shallow copy of all items in this tag. */
    get items(): ApeItem[];
    /**
     * Returns a map of item key (upper-cased) to item, mirroring the C++ `itemListMap()`.
     * @returns A `Map` from uppercased item key to the corresponding {@link ApeItem}.
     */
    itemListMap(): Map<string, ApeItem>;
    /** Find an item by key (case-insensitive). */
    item(key: string): ApeItem | undefined;
    /** Set (or replace) an item. Matching is case-insensitive by key. */
    setItem(item: ApeItem): void;
    /** Remove an item by key (case-insensitive). */
    removeItem(key: string): void;
    properties(): PropertyMap;
    setProperties(props: PropertyMap): PropertyMap;
    /**
     * Render the complete APE tag (header + items + footer).
     */
    render(): ByteVector;
    /**
     * Return the first text value for `key`, or `""` when not present or not a
     * Text-type item.
     *
     * @param key - Upper-cased APE item key.
     */
    private textValue;
    /**
     * Set `key` to a single text value, or remove the item when `value` is `""`.
     *
     * @param key - Upper-cased APE item key.
     * @param value - Value to store, or `""` to remove.
     */
    private setTextValue;
    /**
     * Set a text value under `key`, simultaneously removing any legacy aliases
     * for the same field (e.g. replacing "DATE" when writing "YEAR").
     */
    private setTextValueExclusive;
}
//# sourceMappingURL=apeTag.d.ts.map