/** @packageDocumentation ID3v2 tag implementation supporting read, write, and PropertyMap access for all standard frame types. */ import { ByteVector } from "../../byteVector.js"; import { Tag } from "../../tag.js"; import { PropertyMap } from "../../toolkit/propertyMap.js"; import type { VariantMap } from "../../toolkit/variant.js"; import type { offset_t } from "../../toolkit/types.js"; import type { IOStream } from "../../toolkit/ioStream.js"; import { Id3v2Header } from "./id3v2Header.js"; import { Id3v2ExtendedHeader } from "./id3v2ExtendedHeader.js"; import { Id3v2Footer } from "./id3v2Footer.js"; import type { Id3v2Frame } from "./id3v2Frame.js"; import { Id3v2FrameFactory } from "./id3v2FrameFactory.js"; /** * Standard frame ID → property name mapping for ID3v2. * Maps four-character frame IDs (e.g. `"TIT2"`) to TagLib property names (e.g. `"TITLE"`). * @internal */ export declare const frameIdToProperty: Map; /** * ID3v2 tag implementation. */ export declare class Id3v2Tag extends Tag { /** The tag header (version, flags, size). */ private _header; /** The optional extended header, present when the corresponding header flag is set. */ private _extendedHeader; /** The optional footer (v2.4 only), present when the footer-present header flag is set. */ private _footer; /** Ordered list of all frames contained in this tag. */ private _frames; /** Creates a new, empty ID3v2 tag with a default version-4 header. */ constructor(); /** * An ID3v2 tag is empty only when it contains no frames at all. * This ensures tags that contain only non-text frames (e.g. APIC pictures) * are not incorrectly stripped during save. */ get isEmpty(): boolean; /** * Asynchronously read an ID3v2 tag from a stream at the given offset. * Returns a `Promise`. */ static readFrom(stream: IOStream, offset: offset_t, factory?: Id3v2FrameFactory): Promise; /** Gets the track title from the TIT2 frame. */ get title(): string; /** * Sets the track title in the TIT2 frame. * @param value - The title string; pass an empty string to remove the frame. */ set title(value: string); /** Gets the lead artist/performer from the TPE1 frame. */ get artist(): string; /** * Sets the lead artist/performer in the TPE1 frame. * @param value - The artist string; pass an empty string to remove the frame. */ set artist(value: string); /** Gets the album name from the TALB frame. */ get album(): string; /** * Sets the album name in the TALB frame. * @param value - The album string; pass an empty string to remove the frame. */ set album(value: string); /** Gets the comment text from the first available COMM frame. */ get comment(): string; /** * Sets the comment in a COMM frame, creating one if none exists. * @param value - The comment string; pass an empty string to remove all COMM frames. */ set comment(value: string); /** Gets the genre, resolving any ID3v1 numeric references in the TCON frame. */ get genre(): string; /** * Sets the genre in the TCON frame. * @param value - The genre string; pass an empty string to remove the frame. */ set genre(value: string); /** Gets the recording year from the TDRC (or legacy TYER) frame as an integer. */ get year(): number; /** * Sets the recording year in the TDRC frame. * @param value - The year as an integer; pass `0` to remove the frame. */ set year(value: number); /** Gets the track number from the TRCK frame; supports "N/Total" format. */ get track(): number; /** * Sets the track number in the TRCK frame. * @param value - The track number; pass `0` to remove the frame. */ set track(value: number); /** Gets the tag header. */ get header(): Id3v2Header; /** Gets the optional extended header, or `null` if none is present. */ get extendedHeader(): Id3v2ExtendedHeader | null; /** Gets the optional footer (v2.4 only), or `null` if none is present. */ get footer(): Id3v2Footer | null; /** Gets a shallow copy of the ordered list of all frames in this tag. */ get frameList(): Id3v2Frame[]; /** * Returns a map of frame ID to frame list, grouping all frames by their four-character ID. * This mirrors the C++ `frameListMap()` method. * @returns A `Map` from frame ID string to the array of frames with that ID. */ frameListMap(): Map; /** * Returns all frames matching the given frame ID. * @param frameId - A four-character frame ID string or `ByteVector`. * @returns An array of matching frames (may be empty). */ frameListByFrameId(frameId: ByteVector | string): Id3v2Frame[]; /** * Appends a frame to the end of the frame list. * @param frame - The frame to add. */ addFrame(frame: Id3v2Frame): void; /** * Removes a specific frame instance from the frame list. * @param frame - The frame to remove (matched by reference). */ removeFrame(frame: Id3v2Frame): void; /** * Removes all frames that match the given frame ID. * @param frameId - A four-character frame ID string or `ByteVector`. */ removeFrames(frameId: ByteVector | string): void; /** * Render the complete ID3v2 tag (header + all frames + padding + optional footer) to a `ByteVector`. * * Padding strategy matches C++ TagLib: * - Minimum padding is always 1024 bytes. * - When an existing tag is being re-written and its frames still fit within * the original allocated space, the original padding is preserved — but * capped at `max(1024, fileSize / 100)` to avoid unbounded growth. * Since we don't have file-size context here the cap is fixed at 1024. * - When the new frames exceed the original allocated space (or when there * is no original tag), exactly 1024 bytes of padding are appended. * * @param version - The ID3v2 major version to render as; defaults to the tag's current version. * @param fileSize - Optional file size used for the 1% padding threshold (default: 0). * @returns The serialised tag bytes. */ render(version?: number, fileSize?: number): ByteVector; /** * Returns a `PropertyMap` built from all frames in the tag. * Text frames are mapped using {@link frameIdToProperty}; TXXX/COMM/USLT/WXXX/UFID * frames receive special handling. * * @returns The populated property map. */ properties(): PropertyMap; /** * Replaces the tag's frames with those derived from the given `PropertyMap`. * Unknown properties are written as TXXX frames. * * @param properties - The property map to apply. * @returns A `PropertyMap` containing properties that could not be stored. */ setProperties(properties: PropertyMap): PropertyMap; /** * Returns the list of complex-property keys supported by this tag. * Currently only `"PICTURE"` is supported. * * @returns An array of complex-property key strings. */ complexPropertyKeys(): string[]; /** * Returns the complex properties for the given key. * For `"PICTURE"`, returns one map per APIC frame with `data`, `mimeType`, * `description`, and `pictureType` entries. * * @param key - The complex-property key (case-insensitive). * @returns An array of variant maps representing the complex property values. */ complexProperties(key: string): VariantMap[]; /** * Replaces complex properties for the given key. * For `"PICTURE"`, all existing APIC frames are removed and replaced with * frames built from the provided variant maps. * * @param key - The complex-property key (case-insensitive). * @param value - An array of variant maps, each describing one property value. * @returns `true` if the key was handled; `false` otherwise. */ setComplexProperties(key: string, value: VariantMap[]): boolean; /** * Retrieves the text value of the first matching text-identification frame. * * @param frameId - The four-character frame ID string. * @returns The frame text, or an empty string if not found. */ private _getTextFrameValue; /** * Sets the text value of the first matching text-identification frame, creating * a new frame if none exists, or removing all frames when `value` is empty. * * @param frameId - The four-character frame ID string. * @param value - The new text value; pass an empty string to remove the frame. */ private _setTextFrameValue; } //# sourceMappingURL=id3v2Tag.d.ts.map