TIKA-4801: Extract cover art from MP3, MP4, Vorbis and FLAC audio (#2983)

* [TIKA-4801] Extract cover art from ID3v2 APIC frames

Pictures embedded in ID3v2 tags (APIC in v2.3/v2.4, PIC in v2.2) are
handed to the standard EmbeddedDocumentExtractor as inline embedded
documents. The declared mime type becomes the embedded Content-Type,
the picture description becomes dc:title and the APIC picture type is
mapped to dc:description via the spec's label list. No new metadata
properties are recorded on the audio document itself: consumers that
only want to know whether cover art exists can use the embedded
document count.

Malformed picture frames (missing encoding, unterminated mime type or
description, empty picture data) are skipped silently, matching the
existing handling of malformed COMM frames. Linked v2.2 pictures
(image format "-->") are skipped as they carry a URL, not image data.

The fixture is a copy of testMP3id3v24.mp3 with a self-crafted APIC
frame (minimal 1x1 PNG) inserted before the existing frames and the
synchsafe tag size rewritten accordingly.

* [TIKA-4801] Extract cover art from the MP4 covr atom

The covr ilst entry, previously skipped explicitly, is handed to the
standard EmbeddedDocumentExtractor as an inline embedded document, one
per data atom (the atom may repeat for multiple images). The data
atom's well-known value type declares the image format (13 = jpeg,
14 = png, 27 = bmp); any other type is left for auto-detection. As in
the ID3v2 commit, no new metadata properties are recorded on the audio
document itself.

The ParseContext needed for the embedded document extractor is plumbed
from MP4Parser through TikaMp4BoxHandler into TikaUserDataBox.

The fixture is a copy of testMP4.m4a with a self-crafted covr entry
(minimal 1x1 PNG, type 14) appended to the ilst box and the ancestor
box sizes patched.

* [TIKA-4801] Extract cover art from Vorbis metadata block pictures

METADATA_BLOCK_PICTURE comments, base64 encoded FLAC picture blocks as
used by Vorbis and Opus (and shared by all Ogg family parsers through
OggAudioParser.extractComments), are handed to the standard
EmbeddedDocumentExtractor as inline embedded documents. The declared
mime type becomes the embedded Content-Type, the description becomes
dc:title and the picture type is mapped to dc:description through the
ID3v2 APIC label list, which the FLAC picture spec reuses. The raw
comment is excluded from the generic vorbis:* passthrough: a giant
base64 metadata value helps nobody once the picture is an embedded
document. Malformed or truncated blocks and linked pictures (mime
"-->") are skipped silently.

Native FLAC PICTURE blocks remain out of scope: vorbis-java 0.8 keeps
them in FlacFile.otherMetadata without a public accessor.

The fixture is a copy of testVORBIS.ogg with a self-crafted
metadata_block_picture comment (minimal 1x1 PNG) inserted into the
comment header packet, with the Ogg page lacing values and CRC
rewritten.

* [TIKA-4801] Extract cover art from native FLAC PICTURE blocks

vorbis-java 0.8 parses the native FLAC metadata blocks but offers no
accessor for them (FlacFile.getOtherMetadata() exists on their master,
unreleased since 0.8 in 2016), so FlacParser walks the metadata region
itself through a second stream over the spooled file: fLaC magic, then
per block 1 header byte (last-block flag plus type) and a 24 bit BE
length, stopping at the last-block flag, at end of stream or at a
block that declares more data than is left. The PICTURE block payload
(type 6) is byte-identical to the metadata_block_picture comment, so
the parsing and inline embedded-document emission are shared with
OggAudioParser through the extracted extractPictureBlock helper,
keeping the semantics of the previous commit unchanged.

Scope is native FLAC only: FLAC-in-Ogg carries its pictures in
metadata_block_picture comments, which the previous commit already
handles, and its PICTURE packets stay out of scope.

The fixture is a copy of testFLAC.flac from the standard integration
tests with a self-crafted PICTURE block (minimal 1x1 PNG) appended
after the previous last metadata block, whose last-block flag is
cleared.

* [TIKA-4801] Emit all embedded pictures, not just the first

An ID3v2.4 tag with several APIC frames only yielded the first
picture. ID3v2.4 encodes frame sizes as synchsafe integers, but
RawTag read them as plain integers, so any frame above 127 bytes,
which every real cover picture is, made the frame walk overshoot
into the middle of the following frames: with two covers the walk
consumed the second APIC as trailing bytes of the first and stopped
in the padding. The pictures were also emitted with that trailing
garbage attached.

RawTag now reads v2.4 frame sizes as synchsafe. Because widespread
taggers (e.g. older iTunes) wrote plain integers into v2.4 tags, the
two readings are disambiguated when they disagree: a size byte with
the high bit set forces plain, otherwise the reading wins that lands
the walk on a plausible next frame (frame id of capitals and digits,
padding, or the tag end). Sizes below 128 bytes, like all frames in
the existing v2.4 fixtures, are identical in both encodings.

The ID3v2.3 (plain sizes) path, the MP4 covr repeats, the FLAC
PICTURE walk and the Vorbis metadata_block_picture loop were checked
against the same loss pattern and were already correct; multi-cover
fixtures and tests for all of them are added as regression coverage.
The MP3 fixtures were generated with ffmpeg -id3v2_version 4 / 3
(front 64x40 png, back 30x30 png, both above 127 bytes); the MP4,
FLAC and Ogg fixtures extend the single-cover fixtures with a second
image (MP4: one covr record with a png and a jpeg data atom).

Author: dschmidt

tika-parsers/tika-parsers-standard/tika-parsers-standard-modules/tika-parser-audiovideo-module/src/main/java/org/apache/tika/parser/mp3/ID3Tags.java

@@ -16,6 +16,7 @@
  */
 package org.apache.tika.parser.mp3;
 
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -163,6 +164,36 @@ public interface ID3Tags {
             /* 125 */ "Dance Hall",
             /* sentinel */ ""};
 
+    /**
+     * List of predefined picture types for embedded pictures, indexed
+     * by the type byte of the ID3v2 APIC / PIC frames. The FLAC picture
+     * block, as also embedded in Vorbis comments, reuses the same list.
+     * <p>
+     * See <a href="https://id3.org/id3v2.4.0-frames">http://id3.org/id3v2.4.0-frames</a>
+     */
+    String[] PICTURE_TYPES = new String[]{
+            /*  0 */ "Other",
+            /*  1 */ "32x32 pixels 'file icon' (PNG only)",
+            /*  2 */ "Other file icon",
+            /*  3 */ "Cover (front)",
+            /*  4 */ "Cover (back)",
+            /*  5 */ "Leaflet page",
+            /*  6 */ "Media (e.g. label side of CD)",
+            /*  7 */ "Lead artist/lead performer/soloist",
+            /*  8 */ "Artist/performer",
+            /*  9 */ "Conductor",
+            /* 10 */ "Band/Orchestra",
+            /* 11 */ "Composer",
+            /* 12 */ "Lyricist/text writer",
+            /* 13 */ "Recording Location",
+            /* 14 */ "During recording",
+            /* 15 */ "During performance",
+            /* 16 */ "Movie/video screen capture",
+            /* 17 */ "A bright coloured fish",
+            /* 18 */ "Illustration",
+            /* 19 */ "Band/artist logotype",
+            /* 20 */ "Publisher/Studio logotype"};
+
     /**
      * Does the file contain this kind of tags?
      */
@@ -198,6 +229,15 @@ public interface ID3Tags {
      */
     List<ID3Comment> getComments();
 
+    /**
+     * Retrieves the embedded pictures (e.g. cover art), if any.
+     * Only ID3v2 tags can carry pictures, so this defaults to
+     * an empty list.
+     */
+    default List<ID3Picture> getPictures() {
+        return Collections.emptyList();
+    }
+
     String getGenre();
 
     String getYear();
@@ -258,4 +298,50 @@ public String getText() {
             return text;
         }
     }
+
+    /**
+     * Represents an embedded picture in ID3 v2, such as cover art,
+     * as carried by the APIC (v2.3/v2.4) and PIC (v2.2) frames
+     */
+    class ID3Picture {
+        private final String mimeType;
+        private final String description;
+        private final int pictureType;
+        private final byte[] data;
+
+        public ID3Picture(String mimeType, String description, int pictureType, byte[] data) {
+            this.mimeType = mimeType;
+            this.description = description;
+            this.pictureType = pictureType;
+            this.data = data;
+        }
+
+        /**
+         * Gets the declared mime type, if present
+         */
+        public String getMimeType() {
+            return mimeType;
+        }
+
+        /**
+         * Gets the description, if present
+         */
+        public String getDescription() {
+            return description;
+        }
+
+        /**
+         * Gets the picture type byte, which indexes {@link #PICTURE_TYPES}
+         */
+        public int getPictureType() {
+            return pictureType;
+        }
+
+        /**
+         * Gets the raw picture data
+         */
+        public byte[] getData() {
+            return data;
+        }
+    }
 }

tika-parsers/tika-parsers-standard/tika-parsers-standard-modules/tika-parser-audiovideo-module/src/main/java/org/apache/tika/parser/mp3/ID3v22Handler.java

@@ -44,6 +44,7 @@ public class ID3v22Handler implements ID3Tags {
     private String albumArtist;
     private String disc;
     private List<ID3Comment> comments = new ArrayList<>();
+    private List<ID3Picture> pictures = new ArrayList<>();
 
     public ID3v22Handler(ID3v2Frame frame) throws IOException, SAXException, TikaException {
         RawTagIterator tags = new RawV22TagIterator(frame);
@@ -78,6 +79,13 @@ public ID3v22Handler(ID3v2Frame frame) throws IOException, SAXException, TikaExc
                     }
                     break;
                 }
+                case "PIC": {
+                    ID3Picture picture = ID3v2Frame.getV22Picture(tag.data, 0, tag.data.length);
+                    if (picture != null) {
+                        pictures.add(picture);
+                    }
+                    break;
+                }
                 case "TRK":
                     trackNumber = getTagString(tag.data, 0, tag.data.length);
                     break;
@@ -149,6 +157,10 @@ public List<ID3Comment> getComments() {
         return comments;
     }
 
+    public List<ID3Picture> getPictures() {
+        return pictures;
+    }
+
     public String getGenre() {
         return genre;
     }

tika-parsers/tika-parsers-standard/tika-parsers-standard-modules/tika-parser-audiovideo-module/src/main/java/org/apache/tika/parser/mp3/ID3v23Handler.java

@@ -45,6 +45,7 @@ public class ID3v23Handler implements ID3Tags {
     private String disc;
     private String compilation;
     private List<ID3Comment> comments = new ArrayList<>();
+    private List<ID3Picture> pictures = new ArrayList<>();
 
     public ID3v23Handler(ID3v2Frame frame) throws IOException, SAXException, TikaException {
         RawTagIterator tags = new RawV23TagIterator(frame);
@@ -79,6 +80,13 @@ public ID3v23Handler(ID3v2Frame frame) throws IOException, SAXException, TikaExc
                     }
                     break;
                 }
+                case "APIC": {
+                    ID3Picture picture = ID3v2Frame.getPicture(tag.data, 0, tag.data.length);
+                    if (picture != null) {
+                        pictures.add(picture);
+                    }
+                    break;
+                }
                 case "TRCK":
                     trackNumber = getTagString(tag.data, 0, tag.data.length);
                     break;
@@ -135,6 +143,10 @@ public List<ID3Comment> getComments() {
         return comments;
     }
 
+    public List<ID3Picture> getPictures() {
+        return pictures;
+    }
+
     public String getGenre() {
         return genre;
     }

tika-parsers/tika-parsers-standard/tika-parsers-standard-modules/tika-parser-audiovideo-module/src/main/java/org/apache/tika/parser/mp3/ID3v24Handler.java

@@ -46,6 +46,7 @@ public class ID3v24Handler implements ID3Tags {
     private String disc;
     private String compilation;
     private List<ID3Comment> comments = new ArrayList<>();
+    private List<ID3Picture> pictures = new ArrayList<>();
 
     public ID3v24Handler(ID3v2Frame frame) throws IOException, SAXException, TikaException {
         RawTagIterator tags = new RawV24TagIterator(frame);
@@ -85,6 +86,13 @@ public ID3v24Handler(ID3v2Frame frame) throws IOException, SAXException, TikaExc
                     }
                     break;
                 }
+                case "APIC": {
+                    ID3Picture picture = ID3v2Frame.getPicture(tag.data, 0, tag.data.length);
+                    if (picture != null) {
+                        pictures.add(picture);
+                    }
+                    break;
+                }
                 case "TRCK":
                     trackNumber = getTagString(tag.data, 0, tag.data.length);
                     break;
@@ -141,6 +149,10 @@ public List<ID3Comment> getComments() {
         return comments;
     }
 
+    public List<ID3Picture> getPictures() {
+        return pictures;
+    }
+
     public String getGenre() {
         return genre;
     }
@@ -163,7 +175,8 @@ public String getCompilation() {
 
     private class RawV24TagIterator extends RawTagIterator {
         private RawV24TagIterator(ID3v2Frame frame) {
-            frame.super(4, 4, 1, 2);
+            //v2.4 frame sizes are synchsafe integers
+            frame.super(4, 4, 1, 2, true);
         }
     }
 }