music-tag-native
v1.2.0
Published
Music tag reader / writter in Node.js / Browser, powered by napi-rs and lofty
Maintainers
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-nativeyarn add music-tag-nativepnpm add music-tag-nativebun add music-tag-nativeUsage
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 promiseMusicFile.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 tobufferOrPathwhen 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 ofsave.path(): string | null- Return the source path for path-loaded files, ornullfor 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 tonullnever 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 | nullartist: string | nullalbum: string | nullalbumArtist: string | nullgenre: string | nullcomposer: string | nullcomment: string | nullyear: number | nullrating: number | nulltrackNumber: number | nulltrackTotal: number | nulldiscNumber: number | nulldiscsTotal: number | nullconductor: string | nulllyricist: string | nullpublisher: string | nulllyrics: string | nullcopyright: string | nulltrackReplayGain: number | nulltrackReplayPeak: number | nullalbumReplayGain: number | nullalbumReplayPeak: number | nullpictures: MetaPicture[] | null
Audio Properties (Read-Only)
quality: 'HQ' | 'SQ' | 'HiRes'- Audio quality classification. Lossy formats areHQ. Lossless formats (FLAC, APE, AIFF, WAV, WavPack, and ALAC/FLAC in MP4) areHiResabove 16 bits or above 48 kHz, otherwiseSQ. For example, a 24-bit / 44.1 kHz FLAC isHiRes.bitDepth: number | null- Bit depthbitRate: number | null- Audio bitrate in kbpssampleRate: number | null- Sample rate in Hzchannels: number | null- Number of channelsduration: number- Duration in millisecondstagType: 'AIFF' | 'APE' | 'ID3V1' | 'ID3V2' | 'ILST' | 'RIFF' | 'VORBIS' | null- Metadata tag type
Album Art
pictures: MetaPicture[] | null- Embedded pictures. Set tonullto remove all pictures.
ReplayGain
trackReplayGain: number | nulltrackReplayPeak: number | nullalbumReplayGain: number | nullalbumReplayPeak: number | null
MetaPicture
Properties for album art and embedded images:
coverType: PictureType- Type of picturemimeType?: string- MIME type (e.g., 'image/jpeg', 'image/png')description?: string- Optional descriptiondata: 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 playSee package.json for all available scripts.
Type Definitions
Full TypeScript definitions are available in index.d.ts.
License
MIT
