taggy 0.1.2+3

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

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 example app.

Installation

Run the following command:

  dart pub add taggy

Usage

Initialization

It can be done in two ways:

• First method:

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

• Second method:

  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'));
  

About TaggyFile

• It gives us a little more information about the file 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

  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 package 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.