User guide · 1.3.0

TagLib Java

TagLib Java reads and edits audio metadata: titles, artists, album art, and the other information stored alongside audio. It is a pure Java adaptation of TagLib, with a common interface for everyday fields and format-specific classes for working with individual tags and frames.

Installation

Version 1.3.0 requires Java 25 or newer. It has no runtime dependencies or native library to install.

<dependency>
  <groupId>cz.skyba</groupId>
  <artifactId>taglib</artifactId>
  <version>1.3.0</version>
</dependency>

repositories { mavenCentral() }
dependencies { implementation("cz.skyba:taglib:1.3.0") }

For JPMS applications, the module name is cz.skyba.taglib. Add requires cz.skyba.taglib; to your module descriptor.

Read a file

import cz.skyba.taglib.TagLib;
import cz.skyba.taglib.PropertyKey;
import java.nio.file.Path;

class ReadTags {
    public static void main(String[] args) {
        var metadata = TagLib.read(Path.of("song.flac"));
        System.out.println(metadata.properties().first(PropertyKey.TITLE));
        System.out.println(metadata.properties().get(PropertyKey.ARTIST));
        System.out.println(metadata.audioProperties().duration());
    }
}

The result is an immutable snapshot. The library opens and closes the file during the call; the returned values remain usable afterward. A missing title is an empty string, and a missing artist property is an empty list. Audio properties include duration, bitrate, sample rate, channel count, and bit depth.

Change a field

TagLib.edit(Path.of("song.flac"))
    .set(PropertyKey.TITLE, "New title")
    .set(PropertyKey.ARTIST, "Artist A", "Artist B")
    .remove(PropertyKey.COMMENT)
    .save();

set replaces every value of a property; remove removes the property. Changes are applied by save(). The request is merged into the file’s current text properties when it is saved. Existing artwork stays in place unless you edit it.

Saving updates the file in place. Keep a copy of the original if you need recovery after a failed write. A read/modify/save cycle does not promise identical tag bytes: values may be normalized, tags may be converted, and padding or layout may change.

Choose an interface

The distinction between editing and replacement matters. TagLib.write(path, properties) removes text keys absent from the map. Read complete replacement before using it for partial updates.

Using 1.3

Use AudioProperties.duration() for a java.time.Duration. The common snapshot’s lengthInSeconds() is deprecated. Read options now have immutable withAudioProperties, withReadStyle, and withMaxMetadataBytes methods. For MP4 item lookup, use findItem to distinguish an absent item from a stored void item. ID3v2 frame operations also accept textual identifiers, such as frameList("TIT2").

Examples on the following pages assume imports from cz.skyba.taglib and java.nio.file.Path; other types use their full names. Paths refer to your own files.