/** @packageDocumentation ID3v2 frame header and abstract base class for all ID3v2 frame types. */ import { ByteVector, StringType } from "../../byteVector.js"; /** * ID3v2 frame header. * * - v2.2: 3-byte frame ID + 3-byte size (big-endian, NOT synchsafe) * - v2.3: 4-byte frame ID + 4-byte size (big-endian, NOT synchsafe) + 2-byte flags * - v2.4: 4-byte frame ID + 4-byte size (synchsafe) + 2-byte flags */ export declare class Id3v2FrameHeader { /** The four-byte (or three-byte for v2.2) frame identifier. */ private _frameId; /** The size of the frame's payload in bytes, as decoded from the header. */ private _frameSize; /** The ID3v2 major version this header was parsed from or will be rendered for. */ private _version; /** Whether the frame should be discarded when the tag is altered. */ private _tagAlterPreservation; /** Whether the frame should be discarded when the file (but not the tag) is altered. */ private _fileAlterPreservation; /** Whether the frame contents are read-only. */ private _readOnly; /** Whether the frame data is zlib-compressed. */ private _compression; /** Whether the frame data is encrypted. */ private _encryption; /** Whether the frame belongs to a group identified by a group byte. */ private _groupIdentity; /** Whether a data-length indicator (4 bytes) precedes the frame payload. */ private _dataLengthIndicator; /** Whether the frame payload has had unsynchronisation applied (v2.4 per-frame). */ private _unsynchronisation; /** * Construct an `Id3v2FrameHeader`. * * - If both `data` and `version` are provided, the header is parsed from `data`. * - If only `data` is provided, it is used directly as the frame ID. * - If neither is provided, an empty header is created. * * @param data - Raw header bytes to parse, or a frame ID `ByteVector`. * @param version - ID3v2 major version (2, 3, or 4). */ constructor(data?: ByteVector, version?: number); /** * Parse the raw header bytes for the given version, populating all fields. * * @param data - The raw frame header bytes (at least 6 or 10 bytes). * @param version - ID3v2 major version (2, 3, or 4). */ private _parseHeader; /** * Parse the two status/format flag bytes for the given version. * * @param flagsData - The 2-byte flags data (bytes 8-9 of the frame header). * @param version - ID3v2 major version (3 or 4); other values are ignored. */ private _parseFlags; /** Gets the frame identifier as a `ByteVector`. */ get frameId(): ByteVector; /** * Sets the frame identifier. * @param id - The new frame ID (copied by value). */ set frameId(id: ByteVector); /** Gets the payload size of the frame in bytes. */ get frameSize(): number; /** * Sets the payload size of the frame in bytes. * @param size - The new payload size. */ set frameSize(size: number); /** Gets the ID3v2 major version associated with this header. */ get version(): number; /** * Sets the ID3v2 major version associated with this header. * @param v - The major version number (2, 3, or 4). */ set version(v: number); /** Gets whether the frame should be discarded when the tag is altered. */ get tagAlterPreservation(): boolean; /** * Sets the tag-alter-preservation flag. * @param v - `true` if the frame should be discarded on tag alteration. */ set tagAlterPreservation(v: boolean); /** Gets whether the frame should be discarded when the file is altered. */ get fileAlterPreservation(): boolean; /** * Sets the file-alter-preservation flag. * @param v - `true` if the frame should be discarded on file alteration. */ set fileAlterPreservation(v: boolean); /** Gets whether the frame contents are read-only. */ get readOnly(): boolean; /** Gets whether the frame data is zlib-compressed. */ get compression(): boolean; /** * Sets the compression flag. * @param v - `true` if the frame data is compressed. */ set compression(v: boolean); /** Gets whether the frame data is encrypted. */ get encryption(): boolean; /** * Sets the encryption flag. * @param v - `true` if the frame data is encrypted. */ set encryption(v: boolean); /** Gets whether the frame belongs to a group identified by a group byte. */ get groupIdentity(): boolean; /** * Sets the group identity flag. * @param v - `true` if a group-identity byte is present in the frame. */ set groupIdentity(v: boolean); /** Gets whether a 4-byte data-length indicator precedes the payload. */ get dataLengthIndicator(): boolean; /** * Sets the data-length-indicator flag. * @param v - `true` if a data-length indicator is present. */ set dataLengthIndicator(v: boolean); /** Gets whether per-frame unsynchronisation has been applied (v2.4 only). */ get unsynchronisation(): boolean; /** * Sets the unsynchronisation flag. * @param v - `true` if the frame payload has been unsynchronised. */ set unsynchronisation(v: boolean); /** * Render the header to its binary representation. * * For v2.2 this produces 6 bytes; for v2.3/v2.4 it produces 10 bytes * (frame ID + size + two flag bytes). * * @returns The serialised header as a `ByteVector`. */ render(): ByteVector; /** * Build the two flag bytes for the current version. * @returns A 2-byte `ByteVector` representing the status and format flags. */ private _renderFlags; /** Header size: 10 bytes for v2.3/v2.4, 6 bytes for v2.2. */ static size(version?: number): number; } /** * Abstract base class for all ID3v2 frame types. * * Subclasses must implement {@link parseFields} and {@link renderFields} to * handle the frame-specific payload. The common frame header is managed here. */ export declare abstract class Id3v2Frame { /** The parsed frame header, containing the frame ID, size, and flags. */ protected _header: Id3v2FrameHeader; /** * Constructs the base frame with an optional pre-built header. * @param header - An existing `Id3v2FrameHeader`; a new empty one is used when omitted. */ protected constructor(header?: Id3v2FrameHeader); /** Gets the frame identifier from the header. */ get frameId(): ByteVector; /** Gets the payload size in bytes from the header. */ get size(): number; /** Gets the frame's header object. */ get header(): Id3v2FrameHeader; /** Render the complete frame (header + fields) for the given version. */ render(version?: number): ByteVector; /** Parse the frame-specific payload (after header decoding). */ protected abstract parseFields(data: ByteVector, version: number): void; /** Render the frame-specific payload for the given version. */ protected abstract renderFields(version: number): ByteVector; /** * Extract the raw field data from a complete frame blob. * * This handles unsynchronisation decoding, data-length indicators, * and (stubbed) decompression. */ protected static fieldData(frameData: ByteVector, header: Id3v2FrameHeader, version: number): ByteVector; } /** * Returns true if the string contains any character whose code point is * greater than 0xFF (i.e. outside the Latin-1 / ISO-8859-1 range). * Used to decide when a Latin1-encoded frame must be upgraded to UTF-8. * Mirrors the logic in C++ TagLib's `TextIdentificationFrame::renderFields()`. */ export declare function needsNonLatin1Encoding(s: string): boolean; /** Return the null terminator for the given encoding. */ export declare function nullTerminator(encoding: StringType): ByteVector; /** Size of the null terminator for the given encoding. */ export declare function nullTerminatorSize(encoding: StringType): number; /** * Find the index of the first null terminator in `data` starting at `offset` * for the given encoding. Returns the byte offset into `data`, or -1. */ export declare function findNullTerminator(data: ByteVector, encoding: StringType, offset?: number): number; //# sourceMappingURL=id3v2Frame.d.ts.map