FAQ
Frequently asked questions about hAudiotagger.
hAudiotagger is a Flutter plugin for reading, writing, and editing audio metadata. It's built on the lofty Rust library via flutter_rust_bridge.
Android, iOS, Linux, macOS, Windows, and Web.
Yes. hAudiotagger is open-source under the MIT License.
| Feature | hAudiotagger | Other solutions |
|---|---|---|
| Platforms | All 6 | Usually 2-3 |
| Web support | Yes (WASM) | Rarely |
| Write support | Yes | Varies |
| Extended metadata | 60+ fields | Limited |
| Chapters | Yes | Rarely |
| Parallel processing | Yes (rayon) | No |
No. Pre-built binaries are downloaded automatically for each platform.
No configuration is needed for native platforms. For web, see Web Setup.
Flutter 3.0.0+ with Dart SDK 3.6.0+.
Use readField when you only need one field. It's faster because it doesn't load the entire metadata:
// Fast: only loads title
final title = await Haudiotagger.readField(path, TagField.title);
// Slower: loads everything
final tag = await Haudiotagger.read(path);- File path — Use on native platforms for best performance
- Bytes — Use on web, or when you already have the file in memory
Use update instead of write:
// This replaces ALL metadata
await Haudiotagger.write(path, Tag(title: 'New Title'));
// This only changes the title
await Haudiotagger.update(path, TagChanges(title: 'New Title'));Use batchWrite or batchUpdate:
// Write same tag to all files
await Haudiotagger.batchWrite(paths, tag);
// Apply same changes to all files
await Haudiotagger.batchUpdateChanges(paths, TagChanges(album: 'New Album'));Use TagPipeline.preview:
final pipeline = TagPipeline()..trimWhitespace();
final result = await pipeline.preview(path);
print(result.changes); // See what would changeMP3, FLAC, MP4/M4A, Ogg Vorbis, Opus, AAC, WAV, AIFF, APE, and WavPack.
Most formats support full read/write. Some formats have limitations:
| Format | Read | Write |
|---|---|---|
| MP3 | Yes | Yes |
| FLAC | Yes | Yes |
| MP4/M4A | Yes | Yes |
| Ogg Vorbis | Yes | Yes |
| Opus | Yes | Yes |
| AAC | Yes | Yes |
| WAV | Yes | Yes |
| AIFF | Yes | Yes |
| APE | Yes | Yes |
| WavPack | Yes | Yes |
Yes. hAudiotagger supports both ID3v2.3 and ID3v2.4, with version detection and conversion.
Browsers cannot access arbitrary local files via file paths due to security sandboxing. Use the *FromBytes variants.
WebAssembly shared memory requires cross-origin isolation. Without it, the WASM module fails to load.
See Web Setup for configuration instructions.
Yes. Web runs single-threaded WASM without parallel processing. For large batch operations, use native platforms.
On native platforms with 100 files:
- Read: 1,282 files/second
- Write: 197 files/second
- Update: 197 files/second
See Performance for details.
- Use file path API on native
- Use batch operations for multiple files
- Use
readFieldwhen you only need one value - Avoid reading bytes when you have file paths
Yes. On native platforms, batch operations use rayon for parallel processing. Web is single-threaded.
All operations can throw HaudiotaggerError:
try {
final tag = await Haudiotagger.read(path);
} on HaudiotaggerError catch (e) {
print('Error: ${e.message}');
}- OpenFile — File not found or inaccessible
- Read — Failed to parse metadata
- Write — Failed to write metadata
- UnsupportedFormat — File format not supported
hAudiotagger returns null for unreadable files or throws HaudiotaggerError. It never panics.
Cross-origin isolation is not enabled. See Web Setup.
Ensure you're using flutter build web and serving from a proper web server.
Some formats have limited support. Check the Supported Formats table.
Use file path API instead of bytes API on native platforms.
Made with ❤️ and 🦀 by Hirdaya Shrestha
