Class Id3v2Tag

ID3v2 tag implementation.

Hierarchy (View Summary)

Tag
- Id3v2Tag

Constructors

constructor

new Id3v2Tag(): Id3v2Tag
Creates a new, empty ID3v2 tag with a default version-4 header.

Returns Id3v2Tag
Overrides Tag.constructor
- Defined in mpeg/id3v2/id3v2Tag.ts:162

Accessors

album

get album(): string
Gets the album name from the TALB frame.

Returns string
Overrides Tag.album
- Defined in mpeg/id3v2/id3v2Tag.ts:276
set album(value: string): void
Sets the album name in the TALB frame.
Parameters
- value: string
  The album string; pass an empty string to remove the frame.
Returns void
Overrides Tag.album
- Defined in mpeg/id3v2/id3v2Tag.ts:284

artist

get artist(): string
Gets the lead artist/performer from the TPE1 frame.

Returns string
Overrides Tag.artist
- Defined in mpeg/id3v2/id3v2Tag.ts:263
set artist(value: string): void
Sets the lead artist/performer in the TPE1 frame.
Parameters
- value: string
  The artist string; pass an empty string to remove the frame.
Returns void
Overrides Tag.artist
- Defined in mpeg/id3v2/id3v2Tag.ts:271

comment

get comment(): string
Gets the comment text from the first available COMM frame.

Returns string
Overrides Tag.comment
- Defined in mpeg/id3v2/id3v2Tag.ts:289
set comment(value: string): void
Sets the comment in a COMM frame, creating one if none exists.
Parameters
- value: string
  The comment string; pass an empty string to remove all COMM frames.
Returns void
Overrides Tag.comment
- Defined in mpeg/id3v2/id3v2Tag.ts:304

extendedHeader

get extendedHeader(): Id3v2ExtendedHeader | null
Gets the optional extended header, or null if none is present.

Returns Id3v2ExtendedHeader | null
- Defined in mpeg/id3v2/id3v2Tag.ts:393

get footer(): Id3v2Footer | null
Gets the optional footer (v2.4 only), or null if none is present.

Returns Id3v2Footer | null
- Defined in mpeg/id3v2/id3v2Tag.ts:398

frameList

get frameList(): Id3v2Frame[]
Gets a shallow copy of the ordered list of all frames in this tag.

Returns Id3v2Frame[]
- Defined in mpeg/id3v2/id3v2Tag.ts:407

genre

get genre(): string
Gets the genre, resolving any ID3v1 numeric references in the TCON frame.

Returns string
Overrides Tag.genre
- Defined in mpeg/id3v2/id3v2Tag.ts:326
set genre(value: string): void
Sets the genre in the TCON frame.
Parameters
- value: string
  The genre string; pass an empty string to remove the frame.
Returns void
Overrides Tag.genre
- Defined in mpeg/id3v2/id3v2Tag.ts:335

get header(): Id3v2Header
Gets the tag header.

Returns Id3v2Header
- Defined in mpeg/id3v2/id3v2Tag.ts:388

isEmpty

get isEmpty(): boolean
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.

Returns boolean
Overrides Tag.isEmpty
- Defined in mpeg/id3v2/id3v2Tag.ts:172

title

get title(): string
Gets the track title from the TIT2 frame.

Returns string
Overrides Tag.title
- Defined in mpeg/id3v2/id3v2Tag.ts:250
set title(value: string): void
Sets the track title in the TIT2 frame.
Parameters
- value: string
  The title string; pass an empty string to remove the frame.
Returns void
Overrides Tag.title
- Defined in mpeg/id3v2/id3v2Tag.ts:258

track

get track(): number
Gets the track number from the TRCK frame; supports "N/Total" format.

Returns number
Overrides Tag.track
- Defined in mpeg/id3v2/id3v2Tag.ts:361
set track(value: number): void
Sets the track number in the TRCK frame.
Parameters
- value: number
  The track number; pass 0 to remove the frame.
Returns void
Overrides Tag.track
- Defined in mpeg/id3v2/id3v2Tag.ts:375

year

get year(): number
Gets the recording year from the TDRC (or legacy TYER) frame as an integer.

Returns number
Overrides Tag.year
- Defined in mpeg/id3v2/id3v2Tag.ts:340
set year(value: number): void
Sets the recording year in the TDRC frame.
Parameters
- value: number
  The year as an integer; pass 0 to remove the frame.
Returns void
Overrides Tag.year
- Defined in mpeg/id3v2/id3v2Tag.ts:351

Methods

addFrame

addFrame(frame: Id3v2Frame): void
Appends a frame to the end of the frame list.
Parameters
- frame: Id3v2Frame
  The frame to add.
Returns void
- Defined in mpeg/id3v2/id3v2Tag.ts:448

complexProperties

complexProperties(key: string): VariantMap[]
Returns the complex properties for the given key. For "PICTURE", returns one map per APIC frame with data, mimeType, description, and pictureType entries.
Parameters
- key: string
  The complex-property key (case-insensitive).
Returns VariantMap[]
An array of variant maps representing the complex property values.
Overrides Tag.complexProperties
- Defined in mpeg/id3v2/id3v2Tag.ts:743

complexPropertyKeys

complexPropertyKeys(): string[]
Returns the list of complex-property keys supported by this tag. Currently only "PICTURE" is supported.

Returns string[]
An array of complex-property key strings.
Overrides Tag.complexPropertyKeys
- Defined in mpeg/id3v2/id3v2Tag.ts:726

frameListByFrameId

frameListByFrameId(frameId: string | ByteVector): Id3v2Frame[]
Returns all frames matching the given frame ID.
Parameters
- frameId: string | ByteVector
  A four-character frame ID string or ByteVector.
Returns Id3v2Frame[]
An array of matching frames (may be empty).
- Defined in mpeg/id3v2/id3v2Tag.ts:435

frameListMap

frameListMap(): Map<string, 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 Map<string, Id3v2Frame[]>
A Map from frame ID string to the array of frames with that ID.
- Defined in mpeg/id3v2/id3v2Tag.ts:416

properties

properties(): PropertyMap
Returns a PropertyMap built from all frames in the tag. Text frames are mapped using frameIdToProperty; TXXX/COMM/USLT/WXXX/UFID frames receive special handling.

Returns PropertyMap
The populated property map.
Overrides Tag.properties
- Defined in mpeg/id3v2/id3v2Tag.ts:564

removeFrame

removeFrame(frame: Id3v2Frame): void
Removes a specific frame instance from the frame list.
Parameters
- frame: Id3v2Frame
  The frame to remove (matched by reference).
Returns void
- Defined in mpeg/id3v2/id3v2Tag.ts:456

removeFrames

removeFrames(frameId: string | ByteVector): void
Removes all frames that match the given frame ID.
Parameters
- frameId: string | ByteVector
  A four-character frame ID string or ByteVector.
Returns void
- Defined in mpeg/id3v2/id3v2Tag.ts:467

removeUnsupportedProperties

removeUnsupportedProperties(_properties: string[]): void
Remove properties that are not supported by this tag format. The default implementation is a no-op; subclasses may override.
Parameters
- _properties: string[]
  Keys of the properties to remove.
Returns void
Inherited from Tag.removeUnsupportedProperties
- Defined in tag.ts:137

render

render(version?: number, fileSize?: number): ByteVector
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.
Parameters
- Optionalversion: number
  The ID3v2 major version to render as; defaults to the tag's current version.
- fileSize: number = 0
  Optional file size used for the 1% padding threshold (default: 0).
Returns ByteVector
The serialised tag bytes.
- Defined in mpeg/id3v2/id3v2Tag.ts:496

setComplexProperties

setComplexProperties(key: string, value: VariantMap[]): boolean
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.
Parameters
- key: string
  The complex-property key (case-insensitive).
- value: VariantMap[]
  An array of variant maps, each describing one property value.
Returns boolean
true if the key was handled; false otherwise.
Overrides Tag.setComplexProperties
- Defined in mpeg/id3v2/id3v2Tag.ts:770

setProperties

setProperties(properties: PropertyMap): PropertyMap
Replaces the tag's frames with those derived from the given PropertyMap. Unknown properties are written as TXXX frames.
Parameters
- properties: PropertyMap
  The property map to apply.
Returns PropertyMap
A PropertyMap containing properties that could not be stored.
Overrides Tag.setProperties
- Defined in mpeg/id3v2/id3v2Tag.ts:653

`Static`duplicate

duplicate(source: Tag, target: Tag, overwrite: boolean): void
Copy tag fields from source to target. When overwrite is false, only empty fields in the target are filled in.
Parameters
- source: Tag
  The tag to copy values from.
- target: Tag
  The tag to copy values into.
- overwrite: boolean
  When true, all fields in target are overwritten; when false, only unset fields are populated.
Returns void
Inherited from Tag.duplicate
- Defined in tag.ts:187

`Static`joinTagValues

joinTagValues(values: string[]): string
Join an array of tag values with " / ".
Parameters
- values: string[]
  The string values to join.
Returns string
A single string with values separated by " / ".
Inherited from Tag.joinTagValues
- Defined in tag.ts:203

`Static`readFrom

readFrom(
    stream: IOStream,
    offset: number,
    factory?: Id3v2FrameFactory,
): Promise<Id3v2Tag>
Asynchronously read an ID3v2 tag from a stream at the given offset. Returns a Promise<Id3v2Tag>.
Parameters
- stream: IOStream
- offset: number
- Optionalfactory: Id3v2FrameFactory
Returns Promise<Id3v2Tag>
- Defined in mpeg/id3v2/id3v2Tag.ts:180

Class Id3v2Tag

Hierarchy (View Summary)

Index

Constructors

Accessors

Methods

Constructors

constructor

Returns Id3v2Tag

Accessors

album

Returns string

Parameters

Returns void

artist

Returns string

Parameters

Returns void

comment

Returns string

Parameters

Returns void

extendedHeader

Returns Id3v2ExtendedHeader | null

footer

Returns Id3v2Footer | null

frameList

Returns Id3v2Frame[]

genre

Returns string

Parameters

Returns void

header

Returns Id3v2Header

isEmpty

Returns boolean

title

Returns string

Parameters

Returns void

track

Returns number

Parameters

Returns void

year

Returns number

Parameters

Returns void

Methods

addFrame

Parameters

Returns void

complexProperties

Parameters

Returns VariantMap[]

complexPropertyKeys

Returns string[]

frameListByFrameId

Parameters

Returns Id3v2Frame[]

frameListMap

Returns Map<string, Id3v2Frame[]>

properties

Returns PropertyMap

removeFrame

Parameters

Returns void

removeFrames

Parameters

Returns void

removeUnsupportedProperties

Parameters

Returns void

render

Parameters

Returns ByteVector

setComplexProperties

Parameters

Returns boolean

setProperties

`Static`duplicate

`Static`joinTagValues

`Static`readFrom