npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

music-tag-native

v1.2.0

Published

Music tag reader / writter in Node.js / Browser, powered by napi-rs and lofty

Readme

music-tag-native

A high-performance music metadata reader/writer for Node.js and browsers. Read and modify audio file tags (ID3, Vorbis, MP4, etc.) across multiple formats with native performance.

Powered by Rust's lofty crate and napi-rs for native bindings, with WebAssembly support for browsers.

Features

  • Read/Write Metadata: Title, artist, album, year, genre, track numbers, and more
  • Album Art Support: Read and write embedded pictures with multiple formats
  • Audio Properties: Bitrate, sample rate, bit depth, channels, duration
  • Audio Quality Classification: Automatic HQ/SQ/HiRes detection
  • ReplayGain Support: Read and write ReplayGain tags
  • Cross-Platform: Native binaries for macOS, Linux, Windows, Android + WASM for browsers
  • Multiple Formats: MP3, FLAC, M4A, WAV, OGG, and more

Installation

npm install music-tag-native
yarn add music-tag-native
pnpm add music-tag-native
bun add music-tag-native

Usage

Node.js

import { MusicFile } from 'music-tag-native'

// Load from file path
const musicFile = await MusicFile.load('/path/to/audio/file.mp3')
// synchronous:
const musicFileSync = MusicFile.loadSync('/path/to/audio/file.mp3')

// Read metadata
console.log(musicFile.title)
console.log(musicFile.artist)
console.log(musicFile.album)

// Modify metadata
musicFile.title = 'New Title'
musicFile.artist = 'New Artist'
musicFile.year = 2024

// Remove a tag (set to null)
musicFile.albumArtist = null

// Save changes back to file
await musicFile.save()
// synchronous:
musicFile.saveSync()

// Or save to a different file path
await musicFile.save('/path/to/output.mp3')

Browser

import { MusicFile } from 'music-tag-native'

// Load from buffer
const response = await fetch('/url/to/audio/file.mp3')
const arrayBuffer = await response.arrayBuffer()
const buffer = new Uint8Array(arrayBuffer)

// Buffer parsing is asynchronous and rejects when the data is invalid.
const musicFile = await MusicFile.load(buffer)

// Read and modify metadata
console.log(musicFile.title)
musicFile.title = 'New Title'

// Get modified buffer, you need to provide the original data, a new copy with updated tags will be returned
const modifiedBuffer = await musicFile.save(buffer)
// Synchronous APIs block the calling thread while parsing or writing.
const modifiedBufferSync = musicFile.saveSync(buffer)

// Display album art
const pictures = musicFile.pictures
if (pictures && pictures.length > 0) {
  const picture = pictures[0]
  const blob = new Blob([picture.data], { type: picture.mimeType })
  const url = URL.createObjectURL(blob)
  document.querySelector('img').src = url
}

API Reference

MusicFile

Loading Files

  • MusicFile.load(path: string): Promise<MusicFile> - Load audio file from path (Node.js only)
  • MusicFile.loadSync(path: string): MusicFile - Load audio file from path (Node.js only)
  • MusicFile.load(buffer: Uint8Array): Promise<MusicFile> - Load audio file from buffer; parsing errors reject the promise
  • MusicFile.loadSync(buffer: Uint8Array): MusicFile - Load audio file from buffer

Saving Changes

[!note] Path loading and saving are available in Node.js only.

  • save(bufferOrPath?: Uint8Array | string | null): Promise<Uint8Array | void> - Save changes asynchronously. Files loaded from a path are saved to the original path by default, or to bufferOrPath when a path is provided. Files loaded from a buffer require the original buffer and return an updated copy.
  • saveSync(bufferOrPath?: Uint8Array | string | null): Uint8Array | undefined - Synchronous version of save.
  • path(): string | null - Return the source path for path-loaded files, or null for buffer-loaded files.
How path saves work

Every path save, including an in-place save, copies the source file to a temporary file next to the destination, writes the tags there, and then renames it over the destination. An interrupted save never leaves a half-written file. This has some side effects:

  • The destination is a new file. A hard link to the old file keeps the old content. Symlinks are followed, so the link stays and its target is replaced.
  • Permission bits of an existing destination are kept. A new destination gets the source's. Owner/group (Unix), extended attributes and ACLs (Windows) are not copied.
  • Each save copies the whole file, so it needs free space for a second copy of it.
  • An existing destination that is read-only is never replaced: the save throws Destination file '...' is not writable.
  • On Windows, the rename fails while another program holds the destination open without allowing deletion (some media players do).

Which tag is used

Reads and writes use the format's primary tag (e.g. ID3v2 for MP3). Without it, they use another existing tag, and an ID3v1 tag only when nothing else exists, since it is the most limited (30-byte text fields, no pictures).

  • When the tag in use cannot store a field, a primary tag is created with the existing values copied into it.
  • An ID3v1 tag never receives writes directly. Setting a field on an ID3v1-only MP3 creates an ID3v2 tag.
  • An existing ID3v1 tag is updated along with the main tag, so the two do not disagree. Fields ID3v1 cannot store are skipped there.
  • Setting an unsupported field throws, e.g. Rating is not supported by the APE tag. Setting it to null never throws, and never creates a tag.

Metadata Properties (Read/Write)

All properties can be read and written. Set to null to remove a tag.

  • title: string | null
  • artist: string | null
  • album: string | null
  • albumArtist: string | null
  • genre: string | null
  • composer: string | null
  • comment: string | null
  • year: number | null
  • rating: number | null
  • trackNumber: number | null
  • trackTotal: number | null
  • discNumber: number | null
  • discsTotal: number | null
  • conductor: string | null
  • lyricist: string | null
  • publisher: string | null
  • lyrics: string | null
  • copyright: string | null
  • trackReplayGain: number | null
  • trackReplayPeak: number | null
  • albumReplayGain: number | null
  • albumReplayPeak: number | null
  • pictures: MetaPicture[] | null

Audio Properties (Read-Only)

  • quality: 'HQ' | 'SQ' | 'HiRes' - Audio quality classification. Lossy formats are HQ. Lossless formats (FLAC, APE, AIFF, WAV, WavPack, and ALAC/FLAC in MP4) are HiRes above 16 bits or above 48 kHz, otherwise SQ. For example, a 24-bit / 44.1 kHz FLAC is HiRes.
  • bitDepth: number | null - Bit depth
  • bitRate: number | null - Audio bitrate in kbps
  • sampleRate: number | null - Sample rate in Hz
  • channels: number | null - Number of channels
  • duration: number - Duration in milliseconds
  • tagType: 'AIFF' | 'APE' | 'ID3V1' | 'ID3V2' | 'ILST' | 'RIFF' | 'VORBIS' | null - Metadata tag type

Album Art

  • pictures: MetaPicture[] | null - Embedded pictures. Set to null to remove all pictures.

ReplayGain

  • trackReplayGain: number | null
  • trackReplayPeak: number | null
  • albumReplayGain: number | null
  • albumReplayPeak: number | null

MetaPicture

Properties for album art and embedded images:

  • coverType: PictureType - Type of picture
  • mimeType?: string - MIME type (e.g., 'image/jpeg', 'image/png')
  • description?: string - Optional description
  • data: Uint8Array - Image data

PictureType Values

'Cover Art (Other)', 'Cover Art (Png Icon)', 'Cover Art (Icon)', 'Cover Art (Front)', 'Cover Art (Back)', 'Cover Art (Leaflet)', 'Cover Art (Media)', 'Cover Art (Lead Artist)', 'Cover Art (Artist)', 'Cover Art (Conductor)', 'Cover Art (Band)', 'Cover Art (Composer)', 'Cover Art (Lyricist)', 'Cover Art (Recording Location)', 'Cover Art (During Recording)', 'Cover Art (During Performance)', 'Cover Art (Video Capture)', 'Cover Art (Fish)', 'Cover Art (Illustration)', 'Cover Art (Band Logotype)', 'Cover Art (Publisher Logotype)', 'Unknown'

Platform Support

Native binaries are automatically installed for:

  • macOS (x64, ARM64)
  • Linux (x64, ARM64 - GNU and musl)
  • Windows (x64, ia32, ARM64)
  • Android (ARM64)

WebAssembly fallback is available for unsupported platforms and browsers.

Development

# Install dependencies
pnpm install

# Build native addon for current platform
pnpm build

# Build WASM target
pnpm build:wasm

# Run tests
pnpm test

# Run playground
pnpm play

See package.json for all available scripts.

Type Definitions

Full TypeScript definitions are available in index.d.ts.

License

MIT