/** @packageDocumentation Xiph/Vorbis comment tag implementation used by OGG-based formats (Vorbis, Opus, Speex, FLAC-in-OGG). */
import { ByteVector } from "../byteVector.js";
import { Tag } from "../tag.js";
import { PropertyMap } from "../toolkit/propertyMap.js";
import type { VariantMap } from "../toolkit/variant.js";
import { FlacPicture } from "../flac/flacPicture.js";
/**
 * Xiph/Vorbis comment tag implementation.
 *
 * Binary format:
 *   vendorLength(4 LE) + vendor(UTF-8) +
 *   commentCount(4 LE) +
 *   for each: stringLength(4 LE) + "KEY=VALUE"(UTF-8)
 */
export declare class XiphComment extends Tag {
    /** The vendor identification string written by the encoder. */
    private _vendorId;
    /** Map of uppercased field names to their ordered list of values. */
    private _fields;
    /** Track title stored in the "TITLE" field. */
    get title(): string;
    /** @param v - New title string; empty string removes the field. */
    set title(v: string);
    /** Lead artist/performer stored in the "ARTIST" field. */
    get artist(): string;
    /** @param v - New artist string; empty string removes the field. */
    set artist(v: string);
    /** Album title stored in the "ALBUM" field. */
    get album(): string;
    /** @param v - New album string; empty string removes the field. */
    set album(v: string);
    /**
     * User comment, read from "COMMENT" (preferred, matching C++ TagLib default) or
     * "DESCRIPTION" as a fallback for tags written by older encoders.
     * @returns The comment string, or `""` if neither field is set.
     */
    get comment(): string;
    /**
     * Sets the comment. Matches C++ TagLib `XiphComment::setComment()`: if a
     * "DESCRIPTION" field already exists (loaded from file), update that field;
     * otherwise write to "COMMENT" (the standard Vorbis comment field name).
     * @param v - New comment string; empty string removes the field.
     */
    set comment(v: string);
    /** Genre stored in the "GENRE" field. */
    get genre(): string;
    /** @param v - New genre string; empty string removes the field. */
    set genre(v: string);
    /**
     * Release year, read from "DATE" (preferred) or "YEAR" as a fallback.
     * Returns `0` when not set.
     */
    get year(): number;
    /**
     * Sets the year in the "DATE" field and removes any "YEAR" alias.
     * @param v - Four-digit year, or `0` to remove the field.
     */
    set year(v: number);
    /**
     * Track number, read from "TRACKNUMBER" (preferred) or "TRACKNUM" as a fallback.
     * Returns `0` when not set.
     */
    get track(): number;
    /**
     * Sets the track number in "TRACKNUMBER" and removes any "TRACKNUM" alias.
     * @param v - Track number, or `0` to remove the field.
     */
    set track(v: number);
    /**
     * A Xiph comment is empty when all field lists are empty.
     * This matches the C++ TagLib behaviour and ensures tags with only
     * METADATA_BLOCK_PICTURE or other non-standard fields are not stripped.
     */
    get isEmpty(): boolean;
    /**
     * Parse a Xiph comment block from the given ByteVector.
     * @param data   Raw bytes containing the Vorbis comment
     * @param offset Starting position within `data` (default 0)
     */
    static readFrom(data: ByteVector, offset?: number): XiphComment;
    /** The vendor identification string embedded in the comment header. */
    get vendorId(): string;
    /** @param v - New vendor ID string. */
    set vendorId(v: string);
    /** Total number of individual field values across all keys. */
    get fieldCount(): number;
    /**
     * Returns a shallow copy of the internal field map.
     * @returns A new `Map` of uppercased field names to their value arrays.
     */
    fieldListMap(): Map<string, string[]>;
    /**
     * Add or replace a field value.
     * @param key     Field name (case-insensitive, stored uppercase)
     * @param value   The value to set. Empty string removes the field.
     * @param replace If true (default), replaces all existing values for this key
     */
    addField(key: string, value: string, replace?: boolean): void;
    /**
     * Remove all values for the specified field key.
     * @param key - Field name (case-insensitive).
     */
    removeField(key: string): void;
    /**
     * Remove a specific value from the specified field key.
     * Other values for the same key are left intact.
     * @param key - Field name (case-insensitive).
     * @param value - The exact value to remove.
     */
    removeField(key: string, value: string): void;
    /** Remove all fields from this comment, leaving an empty tag. */
    removeAllFields(): void;
    /**
     * Check whether a field with the given key is present.
     * @param key - Field name (case-insensitive).
     * @returns `true` if at least one value exists for `key`.
     */
    contains(key: string): boolean;
    /**
     * Validate a Vorbis comment field key.
     *
     * Keys must consist only of ASCII characters in the range 0x20–0x7D,
     * excluding `'='` (0x3D), and must be at least one character long.
     * @param key - The field key to validate.
     * @returns `true` if the key is valid.
     */
    static checkKey(key: string): boolean;
    /**
     * Decode and return all embedded pictures from METADATA_BLOCK_PICTURE fields.
     * @returns Array of {@link FlacPicture} objects decoded from Base64, or an empty array if none.
     */
    pictureList(): FlacPicture[];
    /**
     * Encode and append a picture to the METADATA_BLOCK_PICTURE field.
     * @param picture - The {@link FlacPicture} to embed as Base64-encoded data.
     */
    addPicture(picture: FlacPicture): void;
    /**
     * Remove a specific picture from the METADATA_BLOCK_PICTURE field.
     * @param picture - The {@link FlacPicture} to remove (matched by rendered bytes).
     */
    removePicture(picture: FlacPicture): void;
    /** Remove all pictures by deleting the METADATA_BLOCK_PICTURE field entirely. */
    removeAllPictures(): void;
    /**
     * Build a {@link PropertyMap} from all fields, excluding METADATA_BLOCK_PICTURE.
     * @returns A populated {@link PropertyMap} with all text fields.
     */
    properties(): PropertyMap;
    /**
     * Replace tag fields with the provided {@link PropertyMap}.
     * METADATA_BLOCK_PICTURE keys are returned as unsupported.
     * @param props - The properties to set.
     * @returns A {@link PropertyMap} of unsupported properties.
     */
    setProperties(props: PropertyMap): PropertyMap;
    /**
     * Returns the list of complex property keys supported by this tag.
     * @returns `["PICTURE"]` if any embedded pictures are present, otherwise `[]`.
     */
    complexPropertyKeys(): string[];
    /**
     * Returns structured complex property data for the given key.
     * @param key - The complex property key (only "PICTURE" is supported).
     * @returns Array of variant maps describing each embedded picture, or `[]` for unknown keys.
     */
    complexProperties(key: string): VariantMap[];
    /**
     * Replaces all complex properties for the given key.
     * @param key - The complex property key (only "PICTURE" is supported).
     * @param value - Array of variant maps describing each picture to embed.
     * @returns `true` if the key was handled, `false` otherwise.
     */
    setComplexProperties(key: string, value: VariantMap[]): boolean;
    /**
     * Render the Vorbis comment to bytes.
     * @param addFramingBit If true, append a 0x01 framing bit (used in Ogg Vorbis)
     */
    render(addFramingBit?: boolean): ByteVector;
    /**
     * Returns the first value for the given field key, or `""` if absent.
     * @param key - Field name (case-insensitive).
     * @returns The first value string, or `""` if the field is not set.
     */
    private firstFieldValue;
}
//# sourceMappingURL=xiphComment.d.ts.map