Provides a simple yet powerful API for reading, writing and converting audio tags (metadata).

Table of contents:

• Features
  • Planned features ⏳
• Getting started
• Installation
• Usage
  • Initialization
  • About TaggyFile
  • Reading tags
  • Writing tags
  • Removing tags
• Feed back & Contributions
• Acknowledgement

Features

• 📖 Reading audio tags metadata from file.
• 📝 Writing audio tags.
• ✂ Removing audio tags.
• 🎶 Supports a variety of file formats: MP3, MP4, FLAC, and more.

Planned features ⏳

• Batches: write to multiple files at the same time.
• Editing file name: add the option to rename a file based on its track title.
• TaggyFileResult: all public APIs should return a universal result; a value of TaggyFile type or an error of TaggyError type.
• Converting tags

Getting started

• Install the package.
• Read the Usage section to explore Taggy's features.
• For more details: check out the Dart example and Flutter example apps.

Installation

Run the following command:

• For a Dart project:

  dart pub add taggy

• For a Flutter project:

  flutter pub add flutter_taggy

Usage

Initialization

• With Dart

  import 'package:taggy/taggy.dart';
  
  void main(){
  Taggy.initializeFrom(DynamicLibrary.open('path/to/library.dll'));
  }

  Or

  import 'package:taggy/taggy.dart';
  
  // call this helper function which takes care of loading the library for you.
  Taggy.initializeFrom(getTaggyDylibFromDirectory('path/of/binaries/directory'));

• With Flutter

  import 'package:flutter_taggy/flutter_taggy.dart';
  
  void main(){
  // When using the Flutter package, we don't have to pass the dynamic library 
  // ourselves but it'll be automatically fetched then loaded for us.
  // So You only need to add the following line.
  Taggy.initialize();
  
  // build something cool
  }

About TaggyFile

• It gives us a little more information about the file(s) we're reading from or writing to, so alongside the list of Tag, we get:
  • the file size (in bytes).
  • a FileType: whether it's (flac, wav, mpeg, etc).
  • an AudioInfo, which is another type, holds the properties of the audio track.

• you can pretty-print a TaggyFile instance by calling formatAsAString():

  output example

  ``` TaggyFile: { size: 12494053 bytes ~ 12.2 MB, fileType: FileType.Mpeg primaryTagType: TagType.Id3v2, tags: { count: 1, items: [ Tag( tagType: Id3v2, trackTitle: Fine Line, trackArtist: Eminem, trackNumber: 9, trackTotal: 1, discTotal: null, discNumber: null, album: SHADYXV, albumArtist: Various Artists, genre: null, language: null, year: null, recordingDate: null, originalReleaseDate: null, has lyrics: true, pictures: { count: 1, items: [ Picture( picType: PictureType.CoverFront, picData(Bytes): 168312, mimeType: MimeType.Jpeg, width: 1000, height: 1000, colorDepth: 24, numColors: 0, )], }, ), ], }, audio: AudioInfo( channelMask: 3, channels: 2, sampleRate: 44100, audioBitrate: 321, overallBitrate: 326, bitDepth: null, durationSec: 306, ), } ```

Reading tags

• Reading all tags:

  const path = 'path/to/audio/file.mp3';
  
  final TaggyFile taggyFile = await Taggy.readAll(path);
  // you can use the getter which, under the hood, is [taggyFile.tags.firstOrNull]
  print(taggyFile.firstTagIfAny);
  
  // or easily access all returned tags
  for (var tag in taggyFile.tags) {
    print(tag.tagType);
  }

• Reading primary tag:

  final path = 'path/to/audio/file.mp3';
  final TaggyFile taggyFile = await Taggy.readPrimary(path);

• Reading any tag:

  It's similar to readPrimary except that the returned TaggyFile.tags might be empty.

  const path = 'path/to/audio/file.mp3';
  final TaggyFile taggyFile = await Taggy.readyAny(path);
  
  // you can also use [formatAsString], we still get a [TaggyFile].
  print(taggyFile.formatAsString());
  
  // you may want to check if it has any tags
  final hasTags = taggyFile.tags.isNotEmpty();
  // Or use the getter
  final Tag? tag = taggyFile.firstTagIfAny;

Writing tags

• About specifying the TagType

  A tag type is required for creating a new Tag instance. You can:

  • check what TagType the file supports based on its type(extension). see this table.

  • Use the function Taggy.writePrimary() and pass it a Tag with a type of TagType.FilePrimaryType, as shown in example below.

• Example of creating a new Tag

  ```dart Tag getTagInstance(TagType tagType){ return Tag( tagType: tagType, album: 'Some Album', trackTitle: 'some Track', trackArtist: 'Some Artist', trackTotal: 10, trackNumber: 1, discNumber: 1, discTotal: 2, year: 2023, recordingDate: '1/3/2019', language: 'EN', pictures: [ Picture( // zeros are used to demonstrate how to provide a picture's data. picData: Uint8List.fromList([0, 0, 0, 0]), mimeType: MimeType.Jpeg, picType: PictureType.CoverFront, width: 1000, height: 800, ), ], ); } ```

• Writing primary tag:

  final path = 'path/to/audio/file.mp3';
  
  final tagToWrite = getTagInstance(TagType.FilePrimaryType);
  
  final TaggyFile taggyFile = await Taggy.writePrimary(
  path: path, tag: tagToWrite, keepOthers: false);
  
  // On Success, [taggyFile.tags] will contain the newly added tag.
  // NOTE: this tag may not contain the same properties of [tagToWrite].
  final pTag = taggyFile.primaryTag;

• Writing multiple tags:

  In most use-cases, you'll use Taggy.writePrimary() to add/edit an audio tag metadata, but you can also provide multiple tags to be written to the same file.

  final path = 'path/to/audio/file.mp3';
  
  final tags = [
  getTagInstance(TagType.FilePrimaryType),
  getTagInstance(TagType.Id3v1),
  ];
  
  final TaggyFile taggyFile = await Taggy.writeAll(
  path: path, tag: tagToWrite, overrideExistent: true);

Removing tags

• Remove a specific Tag

  You can delete a tag from file by specifying its tag type.

  final path = 'path/to/audio/file.mp3';
  
  // The type of to-remove-tag
  final tagType = TagType.Ape;
  
  final TaggyFile taggyFile = await Taggy.removeTag(path: path, tagType: tagType);

• Remove all tags

  final path = 'path/to/audio/file.mp3';
  final TaggyFile taggyFile = await Taggy.removeAll(path: path);
  
  print(taggyFile.tags);
  // output is []

Feed back & Contributions

• 🐛 Found an issue or encountered a bug? please check the existing issues or create a new one.

• 💪🏻 Want to contribute? Thank you, its always welcomed!. You can start by reading the Contributing guide.

• 🙏🏻 You can also contribute if you ⭐ this repository and 👍🏻 the Dart and Flutter packages on Pub.dev, we do appreciate your love.

Acknowledgement

• lofty: a Rust library which provides Taggy with its functionality.

• Flutter Rust Bridge: connects Rust APIs with Dart & Flutter.