Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Vanilagy/mediabunny/llms.txt

Use this file to discover all available pages before exploring further.

Mediabunny allows you to read and write descriptive metadata tags about media files, such as title, author, date, cover art, and other attached files. Common tags are normalized into a uniform format across different container formats.

​
Reading metadata tags

You can retrieve metadata tags from an input file: 
import { Input, ALL_FORMATS, BlobSource } from 'mediabunny';

const input = new Input({
  source: new BlobSource(file),
  formats: ALL_FORMATS,
});

const tags = await input.getMetadataTags();

​
Available metadata fields

​
Basic information

const tags = await input.getMetadataTags();

tags.title;        // Title of the media (e.g., "Gangnam Style")
tags.description;  // Short description or subtitle
tags.artist;       // Primary artist(s) or creator(s)
tags.album;        // Album, collection, or compilation
tags.albumArtist;  // Main credited artist for the album
tags.genre;        // Genre or category (e.g., "Metal", "Horror")
tags.date;         // Release or recording date (Date object)
tags.lyrics;       // Full text lyrics or transcript
tags.comment;      // Freeform notes or commentary

​
Track and disc numbers

tags.trackNumber;  // Position in album (1-based)
tags.tracksTotal;  // Total tracks in album
tags.discNumber;   // Disc index for multi-disc releases (1-based)
tags.discsTotal;   // Total number of discs

​
Images and cover art

const images = tags.images; // AttachedImage[]

if (images && images.length > 0) {
  const coverArt = images[0];
  
  coverArt.data;        // Uint8Array - raw image data
  coverArt.mimeType;    // 'image/jpeg', 'image/png', etc.
  coverArt.kind;        // 'coverFront' | 'coverBack' | 'unknown'
  coverArt.name;        // Optional file name
  coverArt.description; // Optional description
  
  // Display the image
  const blob = new Blob([coverArt.data], { type: coverArt.mimeType });
  const url = URL.createObjectURL(blob);
  imgElement.src = url;
}

​
Raw metadata

The raw field contains the underlying metadata tags, which differ by format: 
tags.raw; // Record<string, string | Uint8Array | RichImageData | AttachedFile | null>
This is useful for:
  • Accessing format-specific metadata that Mediabunny doesn’t normalize
  • Preserving all original metadata when converting files
  • Writing custom metadata tags

​
Writing metadata tags

You can write metadata tags when creating an output file: 
import { Output, Mp4OutputFormat, BufferTarget } from 'mediabunny';

const output = new Output({
  format: new Mp4OutputFormat(),
  target: new BufferTarget(),
});

output.setMetadataTags({
  title: 'Big Buck Bunny',
  artist: 'Blender Foundation',
  date: new Date('2008-05-20'),
  genre: 'Animation',
  comment: 'Open source animated short film',
});

// Add tracks...
await output.start();
// ...
Metadata tags must be set before calling output.start().

​
Adding cover art

To add cover art or other images to a media file: 
// Read image data
const response = await fetch('/cover.jpg');
const arrayBuffer = await response.arrayBuffer();
const imageData = new Uint8Array(arrayBuffer);

output.setMetadataTags({
  title: 'My Song',
  artist: 'My Band',
  images: [
    {
      data: imageData,
      mimeType: 'image/jpeg',
      kind: 'coverFront',
      name: 'cover.jpg',
      description: 'Album cover',
    },
  ],
});

​
Metadata in conversions

When converting files, you can control how metadata is handled:
By default, metadata is copied from input to output:
const conversion = await Conversion.init({
  input,
  output,
  // tags are automatically copied
});

​
Format-specific metadata

Metadata is stored differently in each container format:
  • Metadata in 'moov'-level 'udta' and 'meta' atoms
  • raw field contains atom names as keys
  • Values derived from 'data' atom content

​
Example: Display all metadata

import { Input, ALL_FORMATS, BlobSource } from 'mediabunny';

const input = new Input({
  source: new BlobSource(file),
  formats: ALL_FORMATS,
});

const tags = await input.getMetadataTags();

console.log('Title:', tags.title);
console.log('Artist:', tags.artist);
console.log('Album:', tags.album);
console.log('Date:', tags.date?.toISOString());
console.log('Genre:', tags.genre);

if (tags.images && tags.images.length > 0) {
  console.log(`Found ${tags.images.length} image(s)`);
  
  tags.images.forEach((image, index) => {
    console.log(`Image ${index + 1}:`, {
      kind: image.kind,
      mimeType: image.mimeType,
      size: image.data.byteLength,
    });
  });
}

if (tags.raw) {
  console.log('Raw metadata keys:', Object.keys(tags.raw));
}

​
Example: Add metadata to a new file

import { Output, Mp4OutputFormat, BufferTarget } from 'mediabunny';

const output = new Output({
  format: new Mp4OutputFormat(),
  target: new BufferTarget(),
});

// Fetch album cover
const coverResponse = await fetch('/album-cover.jpg');
const coverData = new Uint8Array(await coverResponse.arrayBuffer());

output.setMetadataTags({
  title: 'My Amazing Song',
  artist: 'The Band Name',
  album: 'The Album Title',
  albumArtist: 'The Band Name',
  trackNumber: 3,
  tracksTotal: 12,
  date: new Date('2024-01-15'),
  genre: 'Rock',
  images: [
    {
      data: coverData,
      mimeType: 'image/jpeg',
      kind: 'coverFront',
    },
  ],
});

// Add tracks and finalize...

Build docs developers (and LLMs) love

Get started for freeTalk to us