Hirdaya-Shrestha/haudiotagger

hAudiotagger

hAudiotagger

Powerful, cross-platform audio metadata for Flutter.

Read · Write · Edit · Analyze · Transform

pub.dev CI MIT License Downloads Live Demo Coverage

Documentation · Live Demo · pub.dev

---

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

---

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.0.1

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,
);

---

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

---

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

• Getting Started
• Examples
• Web Setup
• Platform Notes
• FAQ

Reference

• API Reference
• Extended Metadata
• Chapters
• TagPipeline

→ 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:

• ⭐ Star the repository
• 🐛 Report a bug
• 💡 Request a feature
• 🤝 Submit a pull request
• 📢 Share hAudiotagger with other Flutter developers

---

License

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

---

Made with ❤️ and 🦀 by Hirdaya Shrestha