Type

MetadataTags

Represents descriptive (non-technical) metadata about a media file, such as title, author, date, or cover art. Common tags are normalized by Mediabunny into a uniform format, while the raw field can be used to directly read or write the underlying metadata tags (which differ by format).

• For MP4/QuickTime files, the metadata refers to the data in 'moov'-level 'udta' and 'meta' atoms.
• For Matroska files, the metadata refers to the Tags and Attachments elements whose target is 50 (MOVIE).
• For MP3 files, the metadata refers to the ID3v2 or ID3v1 tags.
• For Ogg files, there is no global metadata so instead, the metadata refers to the combined metadata of all tracks, in Vorbis-style comment headers.
• For WAVE files, the metadata refers to the chunks within the RIFF INFO chunk.
• For ADTS files, there is no metadata.

type MetadataTags = {
	title?: string;
	description?: string;
	artist?: string;
	album?: string;
	albumArtist?: string;
	trackNumber?: number;
	tracksTotal?: number;
	discNumber?: number;
	discsTotal?: number;
	genre?: string;
	date?: Date;
	lyrics?: string;
	comment?: string;
	images?: AttachedImage[];
	raw?: Record<string, string | Uint8Array | RichImageData | null>;
};

See AttachedImage and RichImageData.

Used by

• ConversionOptions.tags
• Input.getMetadataTags()
• Output.setMetadataTags()

Properties

title

title?: string;

Title of the media (e.g. Gangnam Style, Titanic, etc.)

description

description?: string;

Short description or subtitle of the media.

artist

artist?: string;

Primary artist(s) or creator(s) of the work.

album

album?: string;

Album, collection, or compilation the media belongs to.

albumArtist

albumArtist?: string;

Main credited artist for the album/collection as a whole.

trackNumber

trackNumber?: number;

Position of this track within its album or collection (1-based).

tracksTotal

tracksTotal?: number;

Total number of tracks in the album or collection.

discNumber

discNumber?: number;

Disc index if the release spans multiple discs (1-based).

discsTotal

discsTotal?: number;

Total number of discs in the release.

genre

genre?: string;

Genre or category describing the media's style or content (e.g. Metal, Horror, etc.)

date

date?: Date;

Release, recording or creation date of the media.

lyrics

lyrics?: string;

Full text lyrics or transcript associated with the media.

comment

comment?: string;

Freeform notes, remarks or commentary about the media.

images

images?: AttachedImage[];

Embedded images such as cover art, booklet scans, artwork or preview frames.

See AttachedImage.

raw

raw?: Record<string, string | Uint8Array<ArrayBufferLike> | RichImageData | null>;

The raw, underlying metadata tags.

This field can be used for both reading and writing. When reading, it represents the original tags that were used to derive the normalized fields, and any additional metadata that Mediabunny doesn't understand. When writing, it can be used to set arbitrary metadata tags in the output file.

The format of these tags differs per format:

• MP4/QuickTime: By default, the keys refer to the names of the individual atoms in the 'ilst' atom inside the 'meta' atom, and the values are derived from the content of the 'data' atom inside them. When a 'keys' atom is also used, then the keys reflect the keys specified there (such as 'com.apple.quicktime.version'). Additionally, any atoms within the 'udta' atom are dumped into here, however with unknown internal format (Uint8Array).
• Matroska: SimpleTag elements whose target is 50 (MOVIE), either containing string or Uint8Array values.
• MP3: The ID3v2 tags, or a single 'TAG' key with the contents of the ID3v1 tag.
• Ogg: The key-value string pairs from the Vorbis-style comment header (see RFC 7845, Section 5.2). Additionally, the 'vendor' key refers to the vendor string within this header.
• WAVE: The individual metadata chunks within the RIFF INFO chunk. Values are always ISO 8859-1 strings.

See RichImageData.