Getting Started

Installation

Add hAudiotagger to your pubspec.yaml:

dependencies:
  haudiotagger: ^1.3.3

Then run:

flutter pub get

That's it. No native build configuration needed — pre-built binaries are downloaded automatically for each platform.

Quick Start

Read Metadata

import 'package:haudiotagger/haudiotagger.dart';

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

if (tag != null) {
  print('Title: ${tag.title}');
  print('Artist: ${tag.trackArtist}');
  print('Album: ${tag.album}');
  print('Year: ${tag.year}');
  print('Genre: ${tag.genre}');
}

Write Metadata

await Haudiotagger.write('/path/to/song.mp3', Tag(
  title: 'My Song',
  trackArtist: 'Artist Name',
  album: 'Album Name',
  year: 2024,
  genre: 'Rock',
));

Update Metadata (Partial)

Only the fields you specify are changed — everything else stays intact:

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

Batch Operations

Process multiple files at once:

final paths = ['/path/to/song1.mp3', '/path/to/song2.mp3', '/path/to/song3.mp3'];

// Write same tag to all files
final result = await Haudiotagger.batchWrite(paths, Tag(
  album: 'New Album',
));

print('Success: ${result.successes}, Failed: ${result.failures}');

Web Usage

On the web, use the *FromBytes variants:

// Read from bytes
final tag = await Haudiotagger.readFromBytes(fileBytes);

// Write to bytes (returns modified bytes)
final modified = await Haudiotagger.writeToBytes(fileBytes, Tag(
  title: 'My Song',
));

Web Setup

The host page must be cross-origin isolated for WASM shared memory. Add these headers when serving:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Local Development

flutter run -d chrome \
  --web-header=Cross-Origin-Opener-Policy=same-origin \
  --web-header=Cross-Origin-Embedder-Policy=require-corp

Production

Configure your web server to send the required headers. See Web Setup for detailed instructions.

Error Handling

All operations return Result types that can throw HaudiotaggerError:

try {
  final tag = await Haudiotagger.read('/path/to/song.mp3');
} on HaudiotaggerError catch (e) {
  print('Error: ${e.message}');
}

Common errors:

• OpenFile — File not found or corrupted
• Read — Failed to parse metadata
• Write — Failed to write metadata
• UnsupportedFormat — File format not supported

Next Steps

• Examples — Common use cases and patterns
• API Reference — Complete method documentation
• Web Setup — Detailed web configuration

---