audiotagger

This library allow you to read and write ID3 tags to MP3 files. \ Based on JAudiotagger library.

Library actually works only on Android.

Add dependency

dependencies:
  audiotagger: ^2.2.1

Audiotagger need access to read and write storage. \ To do this you can use Permission Handler library.

Table of contents

• Basic usage
• Reading operations
  • Read tags as Tag object
  • Read tags as map
  • Read artwork
  • Read audio file as AudioFile object
  • Read audio file as map
• Writing operations
  • Write tags from map
  • Write tags from Tag object
  • Write single tag field
• Models
  • Tag class
    • Map of Tag
  • AudioFile class
    • Map of AudioFile

Basic usage

Initialize a new instance of the tagger;

final tagger = new Audiotagger();

Reading operations

Read tags as Tag object

Obtain ID3 tags of the file as a Tag object.

void getTags() async {
    final String filePath = "/storage/emulated/0/file.mp3";
    final Tag tag = await tagger.readTags(
        path: filePath
    );
}

This method does not read the artwork of the song. To do this, use the readArtwork method.

The Tag object has this schema: Tag schema.

Read tags as map

Obtain ID3 tags of the file as a Map.

void getTagsAsMap() async {
    final String filePath = "/storage/emulated/0/file.mp3";
    final Map map = await tagger.readTagsAsMap(
        path: filePath
    );
}

This method does not read the artwork of the song. To do this, use the readArtwork method.

The map has this schema: Map of Tag schema.

Read artwork

Obtain the artwork of the song as a Uint8List.

void getArtwork() async {
    final String filePath = "/storage/emulated/0/file.mp3";
    final Uint8List bytes = await tagger.readArtwork(
        path: filePath
    );
}

Read audio file as AudioFile object

Obtain informations about the MP3 file as a Tag object.

void getAudioFile() async {
    final String filePath = "/storage/emulated/0/file.mp3";
    final AudioFile audioFile = await tagger.readAudioFile(
        path: filePath
    );
}

The AudioFile object has this schema: AudioFile schema.

Read audio file as map

Obtain informations about the MP3 file as a Map.

void getAudioFileAsMap() async {
    final String filePath = "/storage/emulated/0/file.mp3";
    final Map map = await tagger.readAudioFileAsMap(
        path: filePath
    );
}

The map has this schema: Map of AudioFile schema.

Writing operations

Write tags from map

You can write the ID3 tags from a Map. \ To reset a field, pass an empty string (""). \ If the value is null, the field will be ignored and it will not be written.

void setTagsFromMap() async {
    final path = "storage/emulated/0/Music/test.mp3";
    final tags = <String, String>{
        "title": "Title of the song",
        "artist": "A fake artist",
        "album": "",    //This field will be reset
        "genre": null,  //This field will not be written
    };

    final result = await tagger.writeTagsFromMap(
        path: path,
        tags: tags
    );
}

The map has this schema: Map of Tag schema.

Write tags from Tag object

You can write the ID3 tags from a Tag object. \ To reset a field, pass an empty string (""). \ If the value is null, the field will be ignored and it will not be written.

void setTags() async {
    final path = "storage/emulated/0/Music/test.mp3";
    final tag = Tag(
        title: "Title of the song",
        artist: "A fake artist",
        album: "",    //This field will be reset
        genre: null,  //This field will not be written
    );

    final result = await tagger.writeTags(
        path: path,
        tag: tag,
    );
}

The Tag object has this schema: Tag schema.

Write single tag field

You can write a single tag field by specifying the field name. \ To reset the field, pass an empty string (""). \ If the value is null, the field will be ignored and it will not be written. \

void setTags() async {
    final path = "storage/emulated/0/Music/test.mp3";

    final result = await tagger.writeTag(
        path: path,
        tagField: "title",
        value: "Title of the song"
    );
}

Refer to Map of Tag schema for fields name.

Models

These are the schemes of the Map and classes asked and returned by Audiotagger.

Tag class

String? title;
String? artist;
String? genre;
String? trackNumber;
String? trackTotal;
String? discNumber;
String? discTotal;
String? lyrics;
String? comment;
String? album;
String? albumArtist;
String? year;
String? artwork; // It represents the file path of the song artwork.

Map of Tag

<String, String>{
    "title": value,
    "artist": value,
    "genre": value,
    "trackNumber": value,
    "trackTotal": value,
    "discNumber": value,
    "discTotal": value,
    "lyrics": value,
    "comment": value,
    "album": value,
    "albumArtist": value,
    "year": value,
    "artwork": value, // Null if obtained from readTags or readTagsAsMap
};

AudioFile class

int? length;
int? bitRate;
String? channels;
String? encodingType;
String? format;
int? sampleRate;
bool? isVariableBitRate;

Map of AudioFile

<String, dynamic?>{
    "length": length,
    "bitRate": bitRate,
    "channels": channels,
    "encodingType": encodingType,
    "format": format,
    "sampleRate": sampleRate,
    "isVariableBitRate": isVariableBitRate,
};

Copyright and license

This library is developed and maintained by Nicolò Rebaioli
:globe_with_meridians: My website
:mailbox: niko.reba@gmail.com

Released under MIT license

Copyright 2021 Nicolò Rebaioli