hAudiotagger

hAudiotagger

Powerful, cross-platform audio metadata for Flutter.

Read · Write · Edit · Analyze · Transform

pub.flutter-io.cn CI MIT License Downloads Live Demo Coverage

Documentation · Live Demo · pub.flutter-io.cn

Why hAudiotagger?

hAudiotagger is a Rust-powered Flutter library for reading, writing, updating, and transforming audio metadata.

It supports Android, iOS, Linux, macOS, Windows, and Web, with native performance powered by lofty and flutter_rust_bridge.

Built for everything from music players and tag editors to media managers, audio libraries, podcast apps, and file organizers.

Highlights

  • 🚀 Rust-powered metadata processing
  • 🌍 Android, iOS, Linux, macOS, Windows & Web
  • 🎵 MP3, FLAC, M4A, OGG, Opus, WAV, AIFF, APE & WavPack
  • 🏷️ Read, write & partially update metadata
  • 🖼️ Artwork and picture management
  • 📚 Extended metadata with 60+ fields
  • ⚡ Parallel batch processing
  • 🔧 Custom tags and ID3 control
  • 🔄 Metadata diff, merge & transformation
  • 🎧 ReplayGain support
  • 📖 MP3 chapter support
  • 🌐 WebAssembly support
  • 📡 Read metadata from remote URLs via HTTP
  • 🧬 Perceptual audio fingerprinting via haudiotagger_fingerprint

Live Demo

Try hAudiotagger directly in your browser.

No installation. No server-side processing. Everything runs locally in your browser.

Try Live Demo

Note

Web applications should use the *FromBytes APIs such as readFromBytes and writeToBytes. See the Web Setup Guide.

Installation

Add hAudiotagger to your pubspec.yaml:

dependencies:
  haudiotagger: ^2.2.0

Or install it from the command line:

flutter pub add haudiotagger

Quick Start

Read metadata

import 'package:haudiotagger/haudiotagger.dart';

final tag = await Haudiotagger.read('/path/to/song.mp3');

print(tag?.title);
print(tag?.artist);
print(tag?.album);

Write metadata

await Haudiotagger.write(
  '/path/to/song.mp3',
  Tag(
    title: 'My Song',
    artist: 'Artist',
    album: 'Album',
  ),
);

Update specific fields

Change only what you need while preserving the rest of the existing metadata:

await Haudiotagger.update(
  '/path/to/song.mp3',
  TagChanges(
    album: 'New Album',
  ),
);

Batch processing

Process multiple files with a single API:

final result = await Haudiotagger.batchWrite(
  paths,
  tag,
);

Read from URL

Fetch metadata directly from a remote audio file:

final tag = await Haudiotagger.readFromUrl(
  'https://example.com/song.mp3',
);

print(tag?.title);
print(tag?.artist);

Supports progressive download and HTTP range requests for efficient partial reads on native platforms.

Note

On web (WASM), readFromUrl downloads the full file before parsing metadata.

Fingerprint audio

Compare recordings by content — copies, renames, and re-encodes match regardless of tags or filenames:

final fp = await Haudiotagger.fingerprint('song.mp3');
final score = await Haudiotagger.similarity(a, b);

print(score); // 1.0 is (near-)identical, 0.0 is unrelated

Note

Fingerprinting is powered by the haudiotagger_fingerprint package. Install it alongside haudiotagger and the calls above just work — without it they throw a StateError telling you to add it. Pure metadata users pay nothing for this.

Supported Formats

Format Read Write Metadata
MP3 ✅ ✅ ID3v2, ID3v1, APE
FLAC ✅ ✅ Vorbis Comments, ID3v2*
MP4 / M4A ✅ ✅ iTunes ilst
Ogg Vorbis ✅ ✅ Vorbis Comments
Opus ✅ ✅ Vorbis Comments
AAC ✅ ✅ ID3v2, ID3v1
WAV ✅ ✅ ID3v2, RIFF INFO
AIFF ✅ ✅ ID3v2, Text Chunks
APE ✅ ✅ APE, ID3v2*, ID3v1
WavPack ✅ ✅ APE, ID3v1

* Read-only where writing is not supported by the underlying format implementation.

Features

Metadata

  • Title, artist, album, album artist
  • Genre, year, track & disc numbers
  • Composer, conductor, grouping
  • Comment and description
  • Lyrics
  • Artwork / embedded pictures
  • Custom tags
  • Extended metadata
  • MusicBrainz identifiers
  • AcoustID
  • ISRC
  • ReplayGain

Advanced Operations

  • Partial metadata updates
  • Batch read/write/update
  • Progress callbacks
  • Metadata diff
  • Configurable merge strategies
  • Metadata validation & normalization
  • ID3v2.3 / ID3v2.4 control
  • ID3v1 removal
  • MP3 chapters
  • Individual field reads
  • Individual picture reads
  • Metadata-driven file renaming
  • TagPipeline transformation engine
  • Remote file metadata via readFromUrl

TagPipeline

Need to transform metadata across thousands of files?

The TagPipeline provides a rule-based transformation engine for building repeatable metadata workflows.

final pipeline = TagPipeline([
  // transformation rules
]);

await pipeline.process(paths);

Use it to build workflows such as:

Read metadata
     ↓
Normalize fields
     ↓
Apply transformation rules
     ↓
Validate metadata
     ↓
Write changes

Perfect for music library managers, tag editors, and automated organization tools.

Performance

Native file-path operations use Rust with parallel processing where applicable.

Benchmarked on Linux using 100 distinct MP3 files (~8 MB each):

Operation 1 File 100 Files
Read 500 f/s 1,282 f/s
Batch Write 29 f/s 197 f/s
Batch Update 25 f/s 197 f/s

Note

Performance depends heavily on storage, file size, metadata complexity, filesystem, and hardware. These numbers are provided as a reference rather than a guaranteed throughput.

Platform Support

Platform Support
Android ✅
iOS ✅
Linux ✅
macOS ✅
Windows ✅
Web ✅

The Web implementation uses WebAssembly and provides byte-based APIs for browser environments.

Documentation

Guides

Reference

→ Read the full documentation

Requirements

  • Flutter >= 3.0.0
  • Dart SDK >= 3.6.0

Contributing

Contributions are welcome! 🎉

If you find a bug, have an idea, or want to improve hAudiotagger:

License

hAudiotagger is open-source software licensed under the MIT License.

Made with ❤️ and 🦀 by Hirdaya Shrestha

Libraries

haudiotagger
haudiotagger_web