/** @packageDocumentation ID3v2 comments frame (COMM). Stores free-form comments with language and description. */
import { ByteVector, StringType } from "../../../byteVector.js";
import { Id3v2Frame, Id3v2FrameHeader } from "../id3v2Frame.js";
/**
 * Comments frame (COMM).
 *
 * Structure: encoding(1) + language(3) + description(null-terminated) + text.
 */
export declare class CommentsFrame extends Id3v2Frame {
    /** Text encoding used for the description and comment text fields. Defaults to UTF-8 to correctly handle all Unicode. */
    private _encoding;
    /**
     * Three-byte ISO-639-2 language code. Stored as empty by default; rendered
     * as `"XXX"` (unknown language) when not exactly 3 bytes — matching C++
     * `CommentsFrame::renderFields()`: `d->language.size() == 3 ? d->language : "XXX"`.
     */
    private _language;
    /** Short content description that distinguishes multiple COMM frames. */
    private _description;
    /** The actual comment text. */
    private _text;
    /**
     * Creates a new, empty CommentsFrame.
     * @param encoding - Text encoding to use for description and comment text.
     *                   Defaults to `StringType.UTF8` so all Unicode characters (including CJK)
     *                   are stored correctly. Note: this differs from the previous Latin-1 default,
     *                   meaning newly created frames will have a different encoding byte (0x03 vs 0x00)
     *                   compared to older taglib-ts output. Frames read from existing files preserve
     *                   whatever encoding was stored on disk.
     */
    constructor(encoding?: StringType);
    /** Gets the text encoding used for description and comment text fields. */
    get encoding(): StringType;
    /** Sets the text encoding used for description and comment text fields. */
    set encoding(e: StringType);
    /** Gets the three-byte ISO-639-2 language code. */
    get language(): ByteVector;
    /**
     * Sets the language code. The value is truncated or padded with spaces to
     * exactly 3 bytes.
     */
    set language(lang: ByteVector);
    /** Gets the short content description. */
    get description(): string;
    /** Sets the short content description. */
    set description(value: string);
    /** Gets the comment text. */
    get text(): string;
    /** Sets the comment text. */
    set text(value: string);
    /**
     * Returns the comment text.
     * @returns The comment text string.
     */
    toString(): string;
    /** @internal Create from raw frame data. */
    static fromData(data: ByteVector, header: Id3v2FrameHeader, version: number): CommentsFrame;
    /**
     * Searches for a `CommentsFrame` with the given description in an ID3v2 tag.
     * @param tag - An object exposing a `frames` array of `Id3v2Frame` instances.
     * @param description - The content description to match against.
     * @returns The first matching `CommentsFrame`, or `null` if none is found.
     */
    static findByDescription(tag: {
        frames?: Id3v2Frame[];
    }, description: string): CommentsFrame | null;
    /**
     * Parses the raw COMM frame field data, populating all comment properties.
     * @param data - Decoded frame field bytes.
     * @param _version - ID3v2 version number (unused for COMM parsing).
     */
    protected parseFields(data: ByteVector, _version: number): void;
    /**
     * Renders the COMM frame field data to bytes.
     * @param _version - ID3v2 version number (unused for COMM rendering).
     * @returns A `ByteVector` containing the encoded COMM field data.
     */
    protected renderFields(_version: number): ByteVector;
}
//# sourceMappingURL=commentsFrame.d.ts.map