TIKA-4779: Add audio:bitrate, audio:is-variable-bitrate and audio:has-drm

[dschmidt]

Part 2 of TIKA-4779, following up on #2947 with the three audio properties that need parser work rather than plain mapping: audio:bitrate (average, bits per second), audio:is-variable-bitrate and audio:has-drm, defined under Tika's own namespace in Audio.java.

MP3: the parser already walks every audio frame for the duration, and since frame duration does not depend on the bitrate, the plain mean over the frames is the exact average and differing frame bitrates are an exact VBR signal. The one special case is the Xing/Info/VBRI tag frame some encoders write first: it is a valid MPEG frame without audio, often at a different bitrate than the stream, so it is detected and excluded (a CBR file with an Info tag would otherwise be misreported as VBR, there is a fixture proving exactly that). I deliberately did not go the usual route of reading the bitrate from the Xing table itself: the full frame walk already happens for the duration, so the exact mean is free and works for files without any tag frame.

Vorbis: the identification header declares upper/nominal/lower rates. Nominal maps to audio:bitrate; a zero-width bracket (upper == lower, no nominal) also pins an exact rate. Fixed rate means all three declared rates agree, or only a zero-width bracket is declared; anything else counts as variable.

MP4/M4A: a TikaMp4SoundHandler (same extension pattern as TIKA-2861) structurally walks the sample description entries. Protected sample entry formats (drms, enca) set audio:has-drm; these markers are readable by design since DRM encrypts the payload, not the metadata. The average bitrate comes from the esds elementary stream descriptor, located as a child box of the entry (honoring the version-dependent entry layout, QuickTime wave wrappers and the optional ES descriptor fields). I deliberately avoided scanning the stsd bytes for fourcc markers: codec private data or a URL field can legally contain the string sinf, and a fixture covers that false positive.

For files with several audio tracks the properties reflect the last sound track's sample description, consistent with how the existing MP4 audio metadata behaves.

Note: the hdlr dispatch hook in TikaMp4BoxHandler overlaps with #2936; whichever merges second has a trivial rebase.

Tests run against real files where the repo has them (testMP4.m4a with a declared average of 256000, the constant bitrate MP3 fixtures, testVORBIS.ogg copied from the integration tests). Synthetic fixtures cover only what no real specimen exercises: a VBR MP3, a CBR MP3 with an Info tag frame, a drms protected M4A and an M4A whose ES descriptor uses the optional fields.

[tballison]

Small nits from my agent:

  1. Audio.HAS_DRM javadoc overstates the implementation. It says "…or a protection scheme ('sinf') box," but the
  code only flags the drms/enca sample-entry formats — it never independently detects a standalone sinf. In
  practice enca entries always carry sinf, so coverage is fine, but the doc implies a check that isn't there. Trim
  the sinf mention or reword to "protected sample entry formats."
  2. Multi-track asymmetry. BITRATE is last-track-wins (documented), but HAS_DRM is any-track-wins (only ever set
  to true). Defensible — arguably more correct for DRM — but the two properties describe "the last track" and "any
  track" respectively. Worth a one-line note in the PR/javadoc if you want it explicit.
  3. M4A with avgBitrate=0 gets no BITRATE even when maxBitrate>0 (some encoders only set max). Acceptable given
  the property is defined as average; just a coverage gap, not a bug.
  4. Vorbis nominal-only ⇒ is-variable-bitrate=true is aggressive but correct in practice (nominal-only is
  quality-mode VBR). Fine as-i

Not sure you need to address any of them. The add vs set, number 2 is ... not clear what the right answer is?

[dschmidt]

1. was a leftover from an earlier iteration that scanned raw bytes for sinf; the javadoc now names only the protected sample entry formats.
2. I think the asymmetry is the correct semantics rather than an accident: has-drm answers "does this file contain protected audio anywhere", so any track sets it, while bitrate describes one stream and follows the same last-sound-track convention as the rest of the MP4 audio metadata. Both javadocs now state their multi-track semantics explicitly.
3. is deliberate: the property is defined as the average, and deriving one from maxBitrate would report a number the encoder never claimed; a separate max-bitrate property would be the clean extension if anyone ever needs it.
4. agreed, leaving as is.