A Kotlin Multiplatform library for write ID3 (v2.3) tag to MP3 files. Java Compatible. Currently, reading ID3 tags is not supported.

Online documentation: https://kingg22.github.io/vibrion-id3/

Disclaimer: This library was inspired on browser-id3-writer for JavaScript/Typescript.

A JavaScript library for writing ID3 tags in the browser. While this implementation was built from scratch in Kotlin Multiplatform and does not reuse code from that project, some implementation and core writer were adapted from it. Some tests use a tag built using it. Full credit to @egoroof for the original concept.

[!NOTE]

This library doesn't read, remove or scan byteArray, only generate the tag. You can use Id3AudioWriter.removeTag(bytearray).

This library works on byteArray, doesn't use files, stream, sink, or other formats. You can open an issue or PR to add a module.

implementation("io.github.kingg22:vibrion-id3:<current-version>")

implementation 'io.github.kingg22:vibrion-id3:<current-version>'

[versions]
vibrion-id3 = "<current-version>"

[libraries]
vibrion-id3 = { group = "io.github.kingg22", name = "vibrion-id3", version.ref = "vibrion-id3" }

<dependency>
    <groupId>io.github.kingg22</groupId>
    <artifactId>vibrion-id3</artifactId>
    <version>current-version</version>
</dependency>

• Android
• JVM (Java compatible)
• Linux X64
• Linux Arm 64
• Mingw X64
• Android Native Arm 32
• Android Native Arm 64
• Android Native X64
• Android Native X86

You required targets are not available? Please make a PR to add it or create an issue.

You need an Export annotation for specific target? Please make a PR to add it or create an issue.

Java inaccessible? Please create an issue with demonstration of the code. I try to make java-friendly.

• Using verbose builder:

  Kotlin:

  val tag: ByteArray = Id3WriterBuilder.id3Writer {
      title = "Song Title Example"
      artist("Example Artist")
      album = "Example Album"
      length = 240_000 // 4 minutos en milisegundos
      year = 2021
      year = null // null is not considered to add frame but is permitted in builder
      picture {
          type = AttachedPictureType.CoverFront
          data = byteArrayOf(0xFF.toByte(), 0xD8.toByte(), 0xFF.toByte()) // Data of image with mimeType JPEG
      }
      syncLyrics {
          line("Just a simple line", timestamp = 1000)
          line("Another line of lyrics", timestamp = 5000)
      }
  }.toByteArray()

  Java builder style:

  final byte[] tag = Id3WriterBuilder.id3Writer()
      .title("Título")
      .artist("Artista")
      .picture(new AttachedPictureBuilder().type(AttachedPictureType.CoverFront).data(new byte[]{
          (byte) 0xFF, (byte) 0xD8, (byte) 0xFF
      }))
      .syncLyrics(new SynchronizedLyricsBuilder().line("a line", 1000).line("other line", 12343))
      .toByteArray();

• Using direct frames and data:

  Kotlin:

  val writer = Id3AudioWriter()
  writer[Id3v2v3TagFrame.TIT2] = "Title"
  writer[Id3v2v3TagFrame.TPE1] = listOf("Eminem", "50 Cent")
  // ⚠️ Advanced use only. May lead to invalid tag structure if not used carefully.
  writer["IPLS"] = PairedTextFrame("key" to "value")
  val tag: ByteArray = writer.build()

  Java:

  class Id3BuilderJavaTest {
    void testBuilderStyle() {
      final var writer = new Id3AudioWriter();
      // Need to call `.INSTANCE` because is a kotlin object.
      writer.set(Id3v2v3TagFrame.TIT2.INSTANCE, "Title");
      writer.set(Id3v2v3TagFrame.TPE1.INSTANCE, List.of("Eminem", "50 Cent"));
      // ⚠️ Advanced use only. May lead to invalid tag structure if not used carefully.
      // Java consumers don't need to use kotlin Pair, can use Map thinking is only for pair key-value
      writer.set("IPLS", new PairedTextFrame(Map.of("key", value)));
      final byte[] tag = writer.build();
      }
  }

A specific frame is not supported and you require it? Please open a PR or create an issue to try to deliver it.

Grouped by type, where (name) is the type in code

Array of strings (StringListFrame):

• TPE1 (song artists)
• TCOM (song composers)
• TCON (song genres)

Pairs of string (PairedTextFrame):

• IPLS (involved people list)

String (TextFrame):

• TLAN (language)
• TIT1 (content group description)
• TIT2 (song title)
• TIT3 (song subtitle)
• TALB (album title)
• TPE2 (album artist)
• TPE3 (conductor/performer refinement)
• TPE4 (interpreted, remixed, or otherwise modified by)
• TRCK (song number in album): '5' or '5/10'
• TPOS (album disc number): '1' or '1/3'
• TPUB (label name)
• TKEY (initial key)
• TMED (media type)
• TDAT (album release date expressed as 'DDMM')
• TSRC (isrc - international standard recording code)
• TSSE (software/hardware and settings used for encoding)
• TCOP (copyright message)
• TCMP (iTunes compilation flag)
• TEXT (lyricist / text writer)

URL (TextFrame):

• WCOM (commercial information)
• WCOP (copyright/Legal information)
• WOAF (official audio file webpage)
• WOAR (official artist/performer webpage)
• WOAS (official audio source webpage)
• WORS (official internet radio station homepage)
• WPAY (payment)
• WPUB (publishers official webpage)

Integer (IntegerFrame):

• TLEN (song duration in milliseconds)
• TYER (album release year)
• TBPM (beats per minute)

Object:

• COMM (CommentFrame) (comments)
• USLT (UnsynchronisedLyrics) (unsychronised lyrics)
• SYLT (SynchronizedLyrics) (synchronised lyrics)
• APIC (AttachedPicture) (attached picture)
• TXXX (UserDefinedText) (user defined text)
• PRIV (PrivateFrame) (private frame)
• WXXX (UserDefinedText) (user defined url link)

• [ ] Kotlin JS / iOS / WASM / WASI target
• [ ] Document all the API
• [ ] Use of contract API, still waiting enable contract for operator set issue.
• [ ] All frames of Id3 v2.3
• [ ] ID3 v2.4 support
• [ ] Maybe, read tags

• ID3v2.3 Official Spec
• ID3v2.3 frames TagLib
• ID3 on Wikipedia

This library is licensed under the MIT License. See LICENSE for details.

Found a bug or missing frame? Contributions are welcome!

• Fork the project
• Create a feature branch
• Write tests if applicable
• Make a pull request

For larger changes (breaking changes, adding features), please open an issue first to discuss ideas.

The library includes unit tests for core frames and encoding logic. See the tests folder for examples. Contributions with additional test coverage are welcome! Contribution for specific Java interop are really welcome!