Pictures, roles, and replacement

Embedded artwork

Embedded artwork is exposed as a list of Picture snapshots. A file can contain several images with the same role. The role describes an image’s purpose in the tag; the MIME type describes its encoding. Neither one is the file extension of the audio container.

Read and export a picture

var pictures = TagLib.read(Path.of("song.flac")).pictures();
for (var picture : pictures) {
    System.out.println(picture.type() + ": " + picture.mimeType());
    System.out.println(picture.description());
}
if (!pictures.isEmpty()) {
    java.nio.file.Files.write(Path.of("artwork.bin"), pictures.getFirst().data());
}

The example exports original bytes, not a converted image. Choose an extension from the MIME type if you need a named image file. The first picture is not necessarily a front cover. Compare picture.type() with PictureType.FRONT_COVER.code() when selecting by role.

A Picture copies bytes on construction, and data() returns another independent copy. The snapshot can be kept after closing the audio file. Unknown width, height, color depth, and indexed color count are zero. Picture.from recognizes an image signature without decoding dimensions.

PictureType and container support

The named roles follow ID3v2/FLAC codes. Common examples are OTHER (0), FRONT_COVER (3), and BACK_COVER (4). There are also roles for icons, artists, performers, and other illustrations. The enum has more values than some containers can preserve.

Use format.supportsPictureType(type) before offering a role in your UI. The role check does not validate image encoding or file write permissions.

Replace one role

TagLib.edit(Path.of("song.flac"))
    .setPicture(PictureType.FRONT_COVER, Path.of("cover.jpg"))
    .removePictures(PictureType.BACK_COVER)
    .save();

setPicture replaces every picture with that role and retains the others. removePictures removes every picture with the specified role. For MP4, use PictureType.OTHER rather than FRONT_COVER.

The image path is read immediately when you call setPicture, even though the audio file is opened only at save time. JPEG, PNG, GIF, BMP, TIFF, and WebP signatures are recognized by Picture.from. Recognition does not imply that every audio format or player supports that encoding.

Supply bytes and descriptive text

var cover = new Picture(
    PictureType.FRONT_COVER,
    "image/jpeg",
    "Front cover",
    java.nio.file.Files.readAllBytes(Path.of("cover.jpg")));
TagLib.edit(Path.of("song.flac")).setPicture(cover).save();

Use this constructor when your application already has the bytes or needs a description. A full overload also accepts width, height, color depth, and indexed color count. Supply known values; passing dimensions does not resize or validate the image. The numeric-role overload can retain an unfamiliar role code read from a file, subject to the container’s support.

Replace the entire list

TagLib.edit(Path.of("song.flac"))
    .replacePictures(java.util.List.of(
        Picture.from(PictureType.FRONT_COVER, Path.of("cover.jpg"))))
    .save();

Pass an empty list to remove all artwork. A replacement discards earlier picture operations on the builder; later operations modify the replacement. Text fields remain subject to their separate edit operations. All saves update the audio file in place.