API Reference

Complete reference for all hAudiotagger methods, types, and error handling.

Core Methods

Read

// Read from file path (native only)
static Future<Tag?> read(String path)

// Read from bytes (web + native)
static Future<Tag?> readFromBytes(Uint8List bytes)

Returns null if no metadata is found. Throws HaudiotaggerError on failure.

Write

// Write to file path (native only)
static Future<void> write(String path, Tag tag)

// Write to bytes (returns modified bytes)
static Future<Uint8List> writeToBytes(Uint8List bytes, Tag tag)

Replaces all existing metadata with the provided tag.

Update

// Update file path (native only)
static Future<void> update(String path, TagChanges changes)

// Update bytes (returns modified bytes)
static Future<Uint8List> updateFromBytes(Uint8List bytes, TagChanges changes)

Only the fields set in changes are modified — everything else stays intact.

Remove

// Remove specific fields from file (native only)
static Future<void> remove(String path, List<TagField> fields)

// Remove from bytes (returns modified bytes)
static Future<Uint8List> removeFromBytes(Uint8List bytes, List<TagField> fields)

Clear

// Clear all metadata from file (native only)
static Future<void> clear(String path)

// Clear from bytes (returns modified bytes)
static Future<Uint8List> clearFromBytes(Uint8List bytes)

---

Single Field Operations

Read Field

// Read one field from file (native only)
static Future<String?> readField(String path, TagField field)

// Read one field from bytes (web + native)
static Future<String?> readFieldFromBytes(Uint8List bytes, TagField field)

Faster than read() when you only need one value.

Supported fields:

• TagField.title
• TagField.artist
• TagField.album
• TagField.albumArtist
• TagField.year
• TagField.genre
• TagField.trackNumber
• TagField.trackTotal
• TagField.discNumber
• TagField.discTotal
• TagField.lyrics
• TagField.comment
• TagField.bpm

Warning

TagField.pictures is not supported — use readPictures() or readPictureByType() instead.

---

Picture Operations

Read Pictures

// Read all pictures from file (native only)
static Future<List<Picture>> readPictures(String path)

// Read all pictures from bytes (web + native)
static Future<List<Picture>> readPicturesFromBytes(Uint8List bytes)

Read Picture by Type

// Read specific picture type from file (native only)
static Future<Picture?> readPictureByType(String path, PictureType type)

// Read specific picture type from bytes (web + native)
static Future<Picture?> readPictureByTypeFromBytes(Uint8List bytes, PictureType type)

Picture types:

• PictureType.other
• PictureType.fileIcon
• PictureType.otherFileIcon
• PictureType.frontCover
• PictureType.backCover
• PictureType.leaflet
• PictureType.media
• PictureType.artist
• PictureType.conductor
• PictureType.band
• PictureType.composer
• PictureType.lyricist
• PictureType.recordingLocation
• PictureType.duringRecording
• PictureType.duringPerformance
• PictureType.movieScreenCapture
• PictureType.colouredFish
• PictureType.illustration
• PictureType.artistLogo
• PictureType.studioLogo

---

Extended Metadata

Get Extended

// Read from file (native only)
static Future<ExtendedTag> getExtended(String path)

// Read from bytes (web + native)
static Future<ExtendedTag> getExtendedFromBytes(Uint8List bytes)

Set Extended

// Write to file (native only)
static Future<void> setExtended(String path, ExtendedTag data)

// Write to bytes (returns modified bytes)
static Future<Uint8List> setExtendedFromBytes(Uint8List bytes, ExtendedTag data)

Replaces all extended fields.

Update Extended

// Partial update on file (native only)
static Future<void> updateExtended(String path, ExtendedChanges changes)

// Partial update on bytes (returns modified bytes)
static Future<Uint8List> updateExtendedFromBytes(Uint8List bytes, ExtendedChanges changes)

Only set fields are modified.

Remove Extended

// Remove from file (native only)
static Future<void> removeExtended(String path)

// Remove from bytes (returns modified bytes)
static Future<Uint8List> removeExtendedFromBytes(Uint8List bytes)

Available fields:

Category	Fields
MusicBrainz	musicBrainzRecordingId, musicBrainzTrackId, musicBrainzReleaseId, musicBrainzReleaseGroupId, musicBrainzArtistId, musicBrainzReleaseArtistId, musicBrainzWorkId, musicBrainzReleaseType
AcoustID	acoustId, acoustIdFingerprint
Identifiers	isrc, barcode, catalogNumber
People	arranger, conductor, director, engineer, lyricist, mixDj, mixEngineer, performer, producer, publisher, label, remixer, writer, composer, originalLyricist
Dates	recordingDate, releaseDate, originalReleaseDate
Style	initialKey, color, mood
URLs	audioFileUrl, audioSourceUrl, commercialInformationUrl, copyrightUrl, trackArtistUrl, radioStationUrl, paymentUrl, publisherUrl
Legal	copyrightMessage, license
Podcast	podcastDescription, podcastSeriesCategory, podcastUrl, podcastGlobalUniqueId, podcastKeywords
Other	setSubtitle, showName, contentGroup, trackSubtitle, language, script, parentalAdvisory, fileOwner, originalFileName, originalMediaType, encodedBy, encoderSoftware, encoderSettings

---

Chapters

Get Chapters

// Read from file (native only)
static Future<List<Chapter>> getChapters(String path)

// Read from bytes (web + native)
static Future<List<Chapter>> getChaptersFromBytes(Uint8List bytes)

Set Chapters

// Write to file (native only)
static Future<void> setChapters(String path, List<Chapter> chapters)

// Write to bytes (returns modified bytes)
static Future<Uint8List> setChaptersFromBytes(Uint8List bytes, List<Chapter> chapters)

---

Custom Tags

Get Custom Tags

// Read from file (native only)
static Future<Map<String, String>> getCustomTags(String path)

// Read from bytes (web + native)
static Future<Map<String, String>> getCustomTagsFromBytes(Uint8List bytes)

Set Custom Tag

// Write to file (native only)
static Future<void> setCustomTag(String path, String key, String value)

// Write to bytes (returns modified bytes)
static Future<Uint8List> setCustomTagFromBytes(Uint8List bytes, String key, String value)

Remove Custom Tag

// Remove from file (native only)
static Future<void> removeCustomTag(String path, String key)

// Remove from bytes (returns modified bytes)
static Future<Uint8List> removeCustomTagFromBytes(Uint8List bytes, String key)

---

Batch Operations

Batch Write

// Write same tag to multiple files
static Future<BatchResult> batchWrite(List<String> paths, Tag tag)

// Write same tag to multiple byte arrays
static Future<BatchBytesResult> batchWriteFromBytes(List<Uint8List> bytesList, Tag tag)

Batch Update Changes

// Apply same changes to multiple files
static Future<BatchResult> batchUpdateChanges(List<String> paths, TagChanges changes)

// Apply same changes to multiple byte arrays
static Future<BatchBytesResult> batchUpdateChangesFromBytes(List<Uint8List> bytesList, TagChanges changes)

Batch Update

// Apply per-file changes with callback
static Future<BatchResult> batchUpdate(
  List<String> paths,
  Tag Function(String path, Tag current) updater, {
  void Function(BatchProgress progress)? onProgress,
})

// Apply per-file changes to byte arrays
static Future<BatchBytesResult> batchUpdateFromBytes(
  List<Uint8List> bytesList,
  Tag Function(int index, Tag current) updater, {
  void Function(BatchProgress progress)? onProgress,
})

---

Utilities

Validate

// Validate file (native only)
static Future<ValidationResult> validate(String path)

// Validate bytes (web + native)
static Future<ValidationResult> validateFromBytes(Uint8List bytes)

// Validate Tag directly
static Future<ValidationResult> validateTag(Tag tag)

Normalize

// Normalize file (native only)
static Future<Tag> normalize(String path)

// Normalize bytes (returns modified bytes)
static Future<Uint8List> normalizeBytes(Uint8List bytes)

// Normalize Tag directly
static Future<Tag> normalizeTag(Tag tag, {NormalizeOptions? options})

NormalizeOptions:

Field	Type	Default
trimValues	bool	true
normalizeWhitespace	bool	true
normalizeUnicode	bool	true
removeEmptyValues	bool	true

Copy Metadata

// Copy between files (native only)
static Future<void> copyMetadata(
  String sourcePath,
  String destPath, {
  bool includeArtwork = true,
  bool includeLyrics = true,
  bool includeCustomTags = true,
})

// Copy between byte arrays
static Future<Uint8List> copyMetadataFromBytes(
  Uint8List sourceBytes,
  Uint8List destBytes, {
  bool includeArtwork = true,
  bool includeLyrics = true,
  bool includeCustomTags = true,
})

Merge Tags

static Tag mergeTags(Tag tagA, Tag tagB, {MergeStrategy? strategy})

MergeStrategy:

• preferFirst — tagA wins for all fields
• preferSecond — tagB wins for all fields
• preferFirstNonEmpty — tagA wins unless empty, then tagB
• preferSecondNonEmpty — tagB wins unless empty, then tagA

Diff Tags

static MetadataDiff diff(Tag oldTag, Tag newTag)

Format Filename

static String formatFilename(Tag tag, {required String pattern})

Placeholders: {title}, {artist}, {album}, {albumArtist}, {track}, {trackTotal}, {disc}, {discTotal}, {year}, {genre}

Rename File

static Future<String> rename(String path, {required String pattern})

Inspect

// Inspect file (native only)
static Future<AudioFileInfo> inspect(String path)

// Inspect bytes (web + native)
static Future<AudioFileInfo> inspectFromBytes(Uint8List bytes)

---

Data Types

Tag

Field	Type	Notes
title	String?
trackArtist	String?
album	String?
albumArtist	String?
year	int?
genre	String?
trackNumber	int?
trackTotal	int?
discNumber	int?
discTotal	int?
lyrics	String?
comment	String?
bpm	double?
duration	int?	Read-only
pictures	List<Picture>
replayGainTrackGain	String?	e.g. "-6.43"
replayGainTrackPeak	String?	e.g. "0.981201"
replayGainAlbumGain	String?	e.g. "-7.12"
replayGainAlbumPeak	String?	e.g. "0.995000"

TagChanges

Same fields as Tag, all optional. Only set fields are applied.

Picture

Field	Type
pictureType	PictureType
mimeType	MimeType?
bytes	Uint8List

Chapter

Field	Type	Notes
title	String	Chapter name
startMs	int	Start time in milliseconds
endMs	int	End time in milliseconds

AudioProperties

Field	Type
duration	Duration?
durationMicros	int?
bitrate	int?
sampleRate	int?
channels	int?
bitsPerSample	int?
codec	String
containerFormat	String
lossless	bool
bitrateMode	BitrateMode
fileSize	BigInt?

AudioFileInfo

Field	Type	Notes
format	String	e.g. MP3, FLAC
tagFormat	String	e.g. ID3v2, VorbisComments
properties	AudioProperties	Technical details
metadata	Tag?	All metadata fields
pictures	List<Picture>	Embedded artwork
size	BigInt	File size in bytes

BatchResult

Field	Type
successes	int
failures	int
errors	List<(String, String)>

BatchBytesResult

Field	Type
results	List<Uint8List>
failures	int
errors	List<(int, String)>

BatchProgress

Field	Type
completed	int
total	int
percent	double

MetadataDiff

Field	Type
changes	List<MetadataChange>
length	int
isEmpty	bool

MetadataChange

Field	Type
field	TagField
oldValue	T?
newValue	T?
type	ChangeType

ValidationResult

Field	Type
issues	List<ValidationIssue>
isValid	bool (getter)

ValidationIssue

Field	Type
field	String
message	String
severity	ValidationSeverity

---

Error Handling

All operations can throw HaudiotaggerError:

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

Error variants:

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

---