Read options, audio properties, and read styles

Reading metadata

TagLib.read(path) returns text properties, embedded pictures, a common-field tag view, and audio properties. These are copied values, independent of an open file. For tags you intend to manipulate through their native representation, use a format-specific file instead.

ReadOptions

Start with ReadOptions.DEFAULT and change only what you need. Each with… call returns a new options value; it does not modify the constant or the value you called it on.

var options = ReadOptions.DEFAULT
    .withReadStyle(ReadStyle.ACCURATE)
    .withMaxMetadataBytes(16 * 1024 * 1024);
var metadata = TagLib.read(Path.of("song.mp3"), options);

What TAGS_ONLY skips

var metadata = TagLib.read(Path.of("song.flac"), ReadOptions.TAGS_ONLY);

TAGS_ONLY is equivalent to ReadOptions.DEFAULT.withAudioProperties(false). It disables optional audio-property parsing. It still reads embedded artwork, so a file containing a large cover can require a substantial allocation.

ASF, DSF, Shorten, and tracker formats parse audio properties even with this setting. For other formats, unrequested audio properties are represented by AudioProperties.EMPTY in a high-level snapshot. A live file’s audioProperties() can instead return null.

Choosing a ReadStyle

Use AVERAGE unless you have a reason to change it. FAST can reduce reads by accepting incomplete discovery or analysis. ACCURATE asks for more thorough processing where the format implements it. These names do not describe a universal algorithm, and several formats use the same reader for all three values.

Upstream TagLib describes read styles as an audio-property tradeoff. In this Java API, the policy also affects metadata discovery and Matroska validation. Turning off audio properties does not disable those effects.

MPEG / MP3 and ADTS AAC

In FAST mode, MPEG tag discovery checks for an initial ID3v2 tag at byte zero. If unrelated data precedes the tag, that tag can be missed. AVERAGE and ACCURATE also search before the first audio frame. This difference still applies with TAGS_ONLY.

For MPEG audio with a valid Xing, Info, or VBRI header, stored frame and byte totals are used to calculate duration and bitrate. Selecting ACCURATE does not force a full frame scan in that case. Without those totals, ordinary MPEG audio uses frame boundaries and bitrate to estimate duration.

ADTS AAC is different: without usable totals, FAST leaves bitrate and duration unknown. AVERAGE samples frames until the average frame size stabilizes; ACCURATE continues through the available frames. Choose the latter if a changing frame size makes the estimate unsuitable.

Matroska / WebM

FAST bounds discovery of the segment and its top-level elements to a 512 KiB window. Metadata outside that discovery window may be absent from the result. The limit concerns where elements are discovered, not a maximum file size or total bytes read. Avoid this mode for an inventory that needs all tags and attachments.

AVERAGE scans the segment’s top-level elements without that window. ACCURATE additionally validates seek and cue references; it can reject a file that a less strict read accepts. It is useful when that validation is wanted, rather than as a blanket setting for every read.

Other formats

Many containers provide duration, sample count, and stream information directly in headers. Their readers can produce the same result for all styles. For example, WavPack accepts a read style but its property reader does not branch on it. Do not assume that FAST improves every format’s performance or that ACCURATE repairs missing or corrupt information.

For a tag-editing tool, the default style is usually the appropriate choice. For a quick scanner, try FAST only if the discovery omissions above are acceptable. Compare your actual file collection before relying on an apparent speed improvement.

Duration and units

var audio = TagLib.read(Path.of("song.flac")).audioProperties();
java.time.Duration duration = audio.duration();
long milliseconds = duration.toMillis();
long wholeSeconds = duration.toSeconds();
int bitrateKbps = audio.bitrate();
int sampleRateHz = audio.sampleRate();

The common duration has millisecond precision. Converting it to whole seconds drops the fractional part for normal, nonnegative durations. Bitrate is in kilobits per second, sample rate is in hertz, and bit depth describes decoded samples. For variable-bitrate audio, a bitrate value can be an average or a nominal rate rather than the rate of every frame.

Unknown numeric values are zero. Duration.ZERO may mean unknown or unrequested duration; it is not evidence that the file contains no audio. Likewise, lossless() == false on AudioProperties.EMPTY does not identify the encoding. Keep the read options or detected format with your result if your application needs to distinguish these cases.

Metadata allocation limits

Use withMaxMetadataBytes when reading files whose metadata size you want to constrain. The minimum is 1,024 bytes. A value such as 16 MiB is a limit you choose for your application, not a recommended maximum for every music collection.

This setting bounds metadata reads and allocations checked by format readers. It is not a total heap budget, a time limit, or a cap on audio payload length. Multiple metadata objects, picture copies, and the returned snapshot can consume more memory than one allocation limit. A file that exceeds a reader’s limit can fail to load; report that failure rather than treating it as an empty tag.