Home

hAudiotagger

Rust-powered audio metadata for Flutter

---

Read, write, and edit audio metadata across Android, iOS, Linux, macOS, Windows, and Web. Built on lofty via flutter_rust_bridge.

Why hAudiotagger?

Most Flutter audio metadata solutions rely on platform-specific native code, forcing you to write separate implementations for each OS. hAudiotagger takes a different approach: one Rust core, compiled to every platform, including Web via WebAssembly.

	hAudiotagger	Platform-specific plugins
Codebase	Single Rust core	Separate per-platform
Web support	WASM (same API)	Usually missing
Consistency	Identical behavior everywhere	Varies by platform
Performance	Rust + rayon parallelism	Depends on implementation
Safety	Panic-free FFI boundary	Varies

Features

Feature	Description
Read / Write metadata	Title, artist, album, artwork, lyrics, and 15 standard fields
Extended metadata	60+ fields: MusicBrainz, AcoustID, ISRC, mood, producer, and more
Chapters	ID3v2 CHAP frames for podcasts and audiobooks
Custom tags	TXXX (ID3v2) and Vorbis non-standard keys
Batch operations	Process hundreds of files with parallel execution
Partial updates	Change one field without touching others
ID3v2 version control	Convert between v2.3 and v2.4
Metadata validation	Detect missing fields, invalid values, and issues
Metadata normalization	Clean whitespace, normalize Unicode, remove empty values
Copy / Merge	Transfer metadata between files with configurable strategies
ReplayGain	Track and album gain/peak values
TagPipeline	56-rule transformation engine for batch processing
File rename	Format and rename files based on metadata

Note

On the web, browsers cannot access arbitrary local files via file paths. Use the *FromBytes variants (e.g. readFromBytes, writeToBytes). On native platforms, both file path and bytes APIs are available.

Quick Start

Installation

dependencies:
  haudiotagger: ^1.3.3

Basic Usage

import 'package:haudiotagger/haudiotagger.dart';

// Read metadata
final tag = await Haudiotagger.read('/path/to/song.mp3');
print(tag?.title);

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

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

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

Web Usage

// Read from bytes (works on web + native)
final tag = await Haudiotagger.readFromBytes(fileBytes);

// Write to bytes
final modified = await Haudiotagger.writeToBytes(fileBytes, tag);

Supported Formats

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

* Read only due to lack of official support

Platform Support

Platform	File Path API	Bytes API	Parallel Processing
Android	Yes	Yes	Yes (rayon)
iOS	Yes	Yes	Yes (rayon)
Linux	Yes	Yes	Yes (rayon)
macOS	Yes	Yes	Yes (rayon)
Windows	Yes	Yes	Yes (rayon)
Web	No	Yes	No (single-threaded WASM)

Performance

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

Benchmarks on Linux with 100 distinct MP3 files (~8 MB each). Values in files per second.

Next Steps

Getting Started	Installation and setup guide
Examples	Common use cases and patterns
API Reference	Complete method documentation
Extended Metadata	MusicBrainz, ISRC, and 60+ fields
Chapters	Podcast and audiobook chapter support
TagPipeline	56-rule transformation engine
Web Setup	Cross-origin isolation and WASM configuration
Platform Notes	Platform-specific considerations
FAQ	Common questions and troubleshooting
Contributing	How to contribute to the project

Requirements

• Flutter >= 3.0.0
• Dart SDK >= 3.6.0

License

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