music-metadata 12.1.1 → 12.2.1

package/README.md

@@ -51,6 +51,7 @@ If you find this project useful and would like to support its development, consi
 | [APE](https://wikipedia.org/wiki/Monkey's_Audio)                          | Monkey's Audio                                            | <img src="./image/logo-APE-AI.svg" width="40" alt="Monkey's Audio logo">                         |
 | [ASF](https://wikipedia.org/wiki/Advanced_Systems_Format)                 | Advanced Systems Format                                   |                                                                                                  |
 | [BWF](https://en.wikipedia.org/wiki/Broadcast_Wave_Format)                | Extended WAV format for broadcast and archiving           |                                                                                                  |
+| [CAF](https://en.wikipedia.org/wiki/Core_Audio_File_Format)               | Core Audio File Format                                    | <img src="./image/logo-Apple_Computer_Logo_rainbow.svg" width="40" alt="Apple rainbow logo">     |
 | [DSDIFF](https://wikipedia.org/wiki/Direct_Stream_Digital)                | Philips DSDIFF                                            | <img src="./image/logo-DSD.svg" width="80" alt="DSD logo">                                       |
 | [DSF](https://wikipedia.org/wiki/Direct_Stream_Digital)                   | Sony's DSD Stream File                                    | <img src="./image/logo-DSD.svg" width="80" alt="DSD logo">                                       |
 | [FLAC](https://wikipedia.org/wiki/FLAC)                                   | Free Lossless Audio Codec                                 | <img src="./image/logo-FLAC.svg" width="80" alt="FLAC logo">                                     |
@@ -80,6 +81,7 @@ Following tag header formats are supported:
 - [RIFF](https://wikipedia.org/wiki/Resource_Interchange_File_Format)/INFO
 - [Vorbis comment](https://wikipedia.org/wiki/Vorbis_comment)
 - [AIFF](https://wikipedia.org/wiki/Audio_Interchange_File_Format)
+- [CAF](https://developer.apple.com/library/archive/documentation/MusicAudio/Reference/CAFSpec/CAF_spec/CAF_spec.html)
  
 Following lyric formats are supported:
 - [LRC](https://en.wikipedia.org/wiki/LRC_(file_format))
@@ -175,6 +177,8 @@ parseFile(filePath: string, options?: IOptions): Promise<IAudioMetadata>
 
 - This function is **Node.js-only** and relies on Node.js-specific APIs to access the filesystem.
 
+- The path must resolve to a regular file. Symlinks to regular files are supported. Directories, FIFOs (named pipes), and other non-regular filesystem objects are rejected with `NotRegularFileError` from `strtok3`. FIFOs are rejected without waiting for a writer. To parse streamed audio, use [`parseStream()`](#parsestream-function).
+
 - For browser environments, consider using the [parseBlob](#parseblob-function) to parse [File object](https://developer.mozilla.org/en-US/docs/Web/API/File) objects.
 
 ##### Example:
@@ -629,6 +633,10 @@ Returns a list of supported MIME-types. This may include some MIME-types which a
   - Metadata not listed in the SeekHead may be skipped.
   - If the SeekHead is missing, this option has no effect.
 
+  For large MKV files on network shares, use `parseFile(filePath, { mkvUseIndex: true })`
+  when the file's SeekHead index is reliable. The default traversal reads every cluster header,
+  so network latency can dominate even though the audio/video payloads are skipped.
+
 - `observer`: `(update: IMetadataEvent) => void`:
 
   Callback function triggered when common tags or format properties are updated during parsing.
@@ -666,8 +674,10 @@ Audio format information. Defined in the TypeScript `IFormat` interface:
 - `format.codec?` Name of the codec (algorithm used for the audio compression)
 - `format.codecProfile?: string` Codec profile / settings
 - `format.tagTypes?: TagType[]`  List of tagging formats found in parsed audio file
-- `format.duration?: number` Duration in seconds
-- `format.bitrate?: number` Number bits per second of encoded audio file
+- `format.duration?: number` Duration in seconds (existing audio/container summary; complete presentation duration for video-only files)
+- `format.bitrate?: number` Existing audio/container summary bitrate in bits per second
+- `format.containerDuration?: number` Complete media presentation duration in seconds, including video
+- `format.overallBitrate?: number` Average bitrate of the entire file in bits per second, including container overhead; requires a known file size and presentation duration
 - `format.sampleRate?: number` Sampling rate in Samples per second (S/s)
 - `format.bitsPerSample?: number` Audio bit depth
 - `format.lossless?: boolean` True if lossless,  false for lossy encoding
@@ -686,9 +696,14 @@ metadata. Import `TrackType` from `music-metadata` to select tracks without know
 ```js
 import { parseFile, TrackType } from 'music-metadata';
 
-const { format } = await parseFile('movie.mp4');
+const { format } = await parseFile('movie.mp4', { duration: true });
 const audioTracks = format.trackInfo.filter(track => track.type === TrackType.audio);
 const videoTracks = format.trackInfo.filter(track => track.type === TrackType.video);
+for (const track of videoTracks) {
+  console.log(track.duration, track.bitrate, track.video?.pixelWidth, track.video?.pixelHeight);
+  console.log(track.video?.frameRate);
+}
+console.log(format.containerDuration, format.overallBitrate);
 ```
 
 Each entry describes one discovered track. The order follows container discovery and does not identify
@@ -698,12 +713,27 @@ logical media streams; Skeleton headers do not create media tracks. Single-strea
 their format properties to one audio track after parsing.
 
 Properties are optional when unavailable and are not copied between tracks. In particular, a container
-or summary bitrate is not a per-track bitrate. MPEG-4 track timing comes from media headers (or parsed
-audio fragments), and track bitrates from sample sizes and duration. ASF supplies audio/video stream
-properties and stream bitrates from both standalone and nested Stream Properties Objects. Codec List
-entries supply names for matching streams; unused codecs do not create tracks. Matroska applies
-specified defaults for flags, language, channels, and sample rate, and prefers IETF language tags when present. Video duration/bitrate coverage and overall
-video statistics remain incomplete. The existing `format` fields retain their summary semantics.
+or summary bitrate is not a per-track bitrate. The existing `format.duration` and `format.bitrate`
+fields retain their summary semantics. Use `containerDuration` for the complete presentation and
+`overallBitrate` for the actual file size multiplied by eight and divided by that duration. These
+statistics remain unset when timing is unavailable; `overallBitrate` also requires a known input size.
+
+MPEG-4 derives audio and video timing from media headers, sample tables, and fragments, including
+fragment defaults and decode timestamps. Track bitrates use sample sizes and duration; video properties
+include encoded dimensions, display dimensions, and average frame rate. ASF supplies stream dimensions,
+stream bitrates, and extended stream timing and frame rate when present. Standalone and nested Stream
+Properties Objects describe actual streams; Codec List entries supply names without creating unused tracks.
+
+Matroska applies specified defaults for flags, language, channels, and sample rate, and prefers IETF
+language tags when present. Track statistics tags provide duration, bitrate, and frame count; without
+these tags, per-track timing may be unavailable even when segment duration is known. Media clusters
+are not scanned to calculate missing track statistics.
+
+Ogg/Theora duration comes from granule positions. Set `duration: true` to allow scanning beyond the
+initial metadata pages. Once a video stream has been fully read, its average bitrate uses that logical
+stream's payload bytes, including codec headers and excluding Ogg framing and other streams. Resolution
+and frame rate are available from the identification header. Audio streams retain their own codec
+bitrate semantics.
 
 For Ogg/Opus, the per-track average bitrate uses the logical stream's payload bytes, including codec
 headers and excluding Ogg framing and other streams. It requires the logical stream's end-of-stream

package/lib/ParserFactory.js

@@ -5,9 +5,10 @@ import { parse as mimeTypeParse } from 'media-typer';
 import { aiffParserLoader } from './aiff/AiffLoader.js';
 import { apeParserLoader } from './apev2/Apev2Loader.js';
 import { asfParserLoader } from './asf/AsfLoader.js';
+import { cafParserLoader } from './caf/CafLoader.js';
 import { getMaxMemoryAllocation } from './common/Allocation.js';
 import { MetadataCollector } from './common/MetadataCollector.js';
-import { createAudioTrackInfo } from './common/TrackInfo.js';
+import { createAudioTrackInfo, finalizeContainerInfo } from './common/TrackInfo.js';
 import { scanAppendingHeaders } from './core.js';
 import { dsdiffParserLoader } from './dsdiff/DsdiffLoader.js';
 import { dsfParserLoader } from './dsf/DsfLoader.js';
@@ -48,7 +49,8 @@ export class ParserFactory {
             wavpackParserLoader,
             musepackParserLoader,
             dsfParserLoader,
-            dsdiffParserLoader
+            dsdiffParserLoader,
+            cafParserLoader
         ].forEach(parser => {
             this.registerParser(parser);
         });
@@ -108,6 +110,7 @@ export class ParserFactory {
                 metadata.setFormat('hasVideo', !!metadata.format.trackInfo.find(track => track.type === TrackType.video));
             }
         }
+        finalizeContainerInfo(metadata, tokenizer.fileInfo.size);
         return metadata.toCommonMetadata();
     }
     /**

package/lib/asf/AsfParser.d.ts

@@ -12,6 +12,7 @@ import { BasicParser } from '../common/BasicParser.js';
 export declare class AsfParser extends BasicParser {
     private streams;
     private codecs;
+    private extendedStreams;
     private streamBitrates;
     parse(): Promise<void>;
     private parseObjectHeaders;

package/lib/asf/AsfParser.js

@@ -22,6 +22,7 @@ const headerType = 'asf';
 export class AsfParser extends BasicParser {
     streams = new Map();
     codecs = [];
+    extendedStreams = new Map();
     streamBitrates = new Map();
     async parse() {
         const header = await this.readToken(AsfObject.TopLevelHeaderObjectToken);
@@ -52,6 +53,7 @@ export class AsfParser extends BasicParser {
                     stream.codecId === new Token.StringType(4, 'ascii').get(codec.information, 0));
             });
             const track = { id: stream.streamNumber, type };
+            const extended = this.extendedStreams.get(stream.streamNumber);
             if (stream.codecId !== undefined) {
                 track.codecId = stream.codecId;
             }
@@ -64,7 +66,20 @@ export class AsfParser extends BasicParser {
             if (stream.video) {
                 track.video = stream.video;
             }
-            const bitrate = this.streamBitrates.get(stream.streamNumber) ?? stream.bitrate;
+            if (extended) {
+                if (extended.endTime > extended.startTime) {
+                    track.duration = Number(extended.endTime - extended.startTime) / 1000;
+                }
+                const name = extended.streamNames[0]?.streamName;
+                if (name) {
+                    track.name = name;
+                }
+                if (track.video && extended.averageTimePerFrame > 0) {
+                    track.video.frameRate = 1e7 / extended.averageTimePerFrame;
+                }
+            }
+            const bitrate = this.streamBitrates.get(stream.streamNumber) ??
+                (extended && extended.dataBitrate > 0 ? extended.dataBitrate : stream.bitrate);
             if (bitrate !== undefined) {
                 track.bitrate = bitrate;
             }
@@ -90,7 +105,13 @@ export class AsfParser extends BasicParser {
                     // 3.2
                     this.validateAllocationSize(payloadSize, 'File Properties Object');
                     const fpo = await this.readToken(new AsfObject.FilePropertiesObject(header));
-                    this.metadata.setFormat('duration', Number(fpo.playDuration / BigInt(1000)) / 10000 - Number(fpo.preroll) / 1000);
+                    if (!fpo.flags.broadcast) {
+                        const duration = Number(fpo.playDuration) / 1e7 - Number(fpo.preroll) / 1000;
+                        if (Number.isFinite(duration) && duration > 0) {
+                            this.metadata.setFormat('duration', duration);
+                            this.metadata.setFormat('containerDuration', duration);
+                        }
+                    }
                     this.metadata.setFormat('bitrate', fpo.maximumBitrate);
                     break;
                 }
@@ -235,6 +256,7 @@ export class AsfParser extends BasicParser {
                     // 4.1
                     this.validateAllocationSize(payloadSize, 'Extended Stream Properties Object');
                     const extended = await this.readToken(new AsfObject.ExtendedStreamPropertiesObjectState(header));
+                    this.extendedStreams.set(extended.streamNumber, extended);
                     if (extended.streamPropertiesObject) {
                         const stream = extended.streamPropertiesObject;
                         this.streams.set(stream.streamNumber, stream);

package/lib/caf/CafLoader.d.ts

@@ -0,0 +1,2 @@
+import type { IParserLoader } from '../ParserFactory.js';
+export declare const cafParserLoader: IParserLoader;

package/lib/caf/CafLoader.js

@@ -0,0 +1,8 @@
+export const cafParserLoader = {
+    parserType: 'caf',
+    extensions: ['.caf', '.caff'],
+    mimeTypes: ['audio/caf', 'application/caf'],
+    async load() {
+        return (await import('./CafParser.js')).CafParser;
+    }
+};

package/lib/caf/CafParser.d.ts

@@ -0,0 +1,37 @@
+import { BasicParser } from '../common/BasicParser.js';
+/**
+ * CAF - Core Audio File Format
+ *
+ * Ref: https://developer.apple.com/library/archive/documentation/MusicAudio/Reference/CAFSpec/CAF_spec/CAF_spec.html
+ */
+export declare class CafParser extends BasicParser {
+    private desc;
+    private packetTable;
+    private dataBytes;
+    private expectedFirstChunk;
+    private reachedEndOfFile;
+    parse(): Promise<void>;
+    private endOfFileReached;
+    private readChunk;
+    private readAudioDescription;
+    private applyAudioDescription;
+    private readPacketTable;
+    private readAudioData;
+    private readInfo;
+    private readChannelLayout;
+    private addChannelLayout;
+    /**
+     * Rejects a whole chunk whose declared size exceeds the remaining input.
+     * Only applicable when the total input size is known.
+     */
+    private validateChunkAvailability;
+    /**
+     * Reads a chunk body without trusting its declared size.
+     * @param chunkSize Declared body size
+     * @param chunkType Chunk name for error messages
+     */
+    private readChunkBody;
+    private skipUnknownChunk;
+    private applyDerivedFormat;
+    private deriveFrameCount;
+}

package/lib/caf/CafParser.js

@@ -0,0 +1,253 @@
+import initDebug from 'debug';
+import * as strtok3 from 'strtok3';
+import * as Token from 'token-types';
+import { BasicParser } from '../common/BasicParser.js';
+import * as CafToken from './CafToken.js';
+import { CafContentError } from './CafToken.js';
+const debug = initDebug('music-metadata:parser:caf');
+// Unrecognised mFormatID values are reported as-is, without claiming losslessness.
+const codecByFormatId = {
+    lpcm: { codec: 'PCM', lossless: true },
+    ima4: { codec: 'IMA4 ADPCM', lossless: false },
+    alac: { codec: 'ALAC', lossless: true },
+    flac: { codec: 'FLAC', lossless: true },
+    ulaw: { codec: 'ITU-T G.711 mu-law', lossless: false },
+    alaw: { codec: 'ITU-T G.711 A-law', lossless: false },
+    '.mp1': { codec: 'MPEG-1 Layer I', lossless: false },
+    '.mp2': { codec: 'MPEG-1 Layer II', lossless: false },
+    '.mp3': { codec: 'MPEG-1 Layer III', lossless: false },
+    'aac ': { codec: 'AAC', lossless: false },
+    aace: { codec: 'AAC', lossless: false },
+    aacf: { codec: 'AAC', lossless: false },
+    aacg: { codec: 'AAC', lossless: false },
+    aach: { codec: 'AAC', lossless: false },
+    aacl: { codec: 'AAC', lossless: false },
+    aacp: { codec: 'AAC', lossless: false }
+};
+const editCountLen = 4;
+const numEntriesLen = 4;
+/**
+ * CAF - Core Audio File Format
+ *
+ * Ref: https://developer.apple.com/library/archive/documentation/MusicAudio/Reference/CAFSpec/CAF_spec/CAF_spec.html
+ */
+export class CafParser extends BasicParser {
+    desc;
+    packetTable;
+    dataBytes;
+    expectedFirstChunk = true;
+    reachedEndOfFile = false;
+    async parse() {
+        const header = await this.tokenizer.readToken(CafToken.FileHeader);
+        if (header.fileType !== 'caff') {
+            throw new CafContentError(`Invalid file-type, expected 'caff', found '${header.fileType}'`);
+        }
+        this.metadata.setFormat('container', 'CAF');
+        this.metadata.setAudioOnly();
+        while (!this.reachedEndOfFile && !this.endOfFileReached()) {
+            let chunkHeader;
+            try {
+                chunkHeader = await this.tokenizer.readToken(CafToken.ChunkHeader);
+            }
+            catch (error) {
+                if (error instanceof strtok3.EndOfStreamError) {
+                    debug('End-of-stream');
+                    break;
+                }
+                throw error;
+            }
+            debug(`Reading CAF chunk type=${chunkHeader.chunkType} size=${chunkHeader.chunkSize}`);
+            if (this.expectedFirstChunk) {
+                this.expectedFirstChunk = false;
+                if (chunkHeader.chunkType !== 'desc') {
+                    throw new CafContentError(`Expected an Audio Description chunk, found '${chunkHeader.chunkType}'`);
+                }
+            }
+            await this.readChunk(chunkHeader);
+        }
+        if (!this.desc) {
+            throw new CafContentError('Missing Audio Description chunk');
+        }
+        this.applyDerivedFormat();
+    }
+    endOfFileReached() {
+        const { size } = this.tokenizer.fileInfo;
+        return size !== undefined && size - this.tokenizer.position < CafToken.ChunkHeader.len;
+    }
+    async readChunk(header) {
+        switch (header.chunkType) {
+            case 'desc':
+                return this.readAudioDescription(header.chunkSize);
+            case 'pakt':
+                return this.readPacketTable(header.chunkSize);
+            case 'data':
+                return this.readAudioData(header.chunkSize);
+            case 'info':
+                return this.readInfo(header.chunkSize);
+            case 'chan':
+                return this.readChannelLayout(header.chunkSize);
+            default:
+                debug(`Ignore chunk type=${header.chunkType} size=${header.chunkSize}`);
+                return this.skipUnknownChunk(header.chunkSize);
+        }
+    }
+    async readAudioDescription(chunkSize) {
+        if (chunkSize < CafToken.AudioDescription.len) {
+            throw new CafContentError(`Audio Description chunk size ${chunkSize} is smaller than ${CafToken.AudioDescription.len}`);
+        }
+        this.desc = await this.tokenizer.readToken(CafToken.AudioDescription);
+        await this.tokenizer.ignore(chunkSize - CafToken.AudioDescription.len);
+        this.applyAudioDescription(this.desc);
+    }
+    applyAudioDescription(desc) {
+        this.metadata.setFormat('sampleRate', desc.sampleRate);
+        this.metadata.setFormat('numberOfChannels', desc.channelsPerFrame);
+        if (desc.bitsPerChannel > 0) {
+            this.metadata.setFormat('bitsPerSample', desc.bitsPerChannel);
+        }
+        const codec = codecByFormatId[desc.formatId];
+        this.metadata.setFormat('codec', codec ? codec.codec : desc.formatId);
+        if (codec) {
+            this.metadata.setFormat('lossless', codec.lossless);
+        }
+    }
+    async readPacketTable(chunkSize) {
+        const desc = this.desc;
+        if (!desc) {
+            throw new CafContentError('Packet Table chunk found before the Audio Description chunk');
+        }
+        if (chunkSize < CafToken.PacketTableHeader.len) {
+            throw new CafContentError(`Packet Table chunk size ${chunkSize} is smaller than ${CafToken.PacketTableHeader.len}`);
+        }
+        this.validateChunkAvailability(chunkSize, 'Packet Table');
+        const packetTable = await this.tokenizer.readToken(CafToken.PacketTableHeader);
+        const body = await this.readChunkBody(chunkSize - CafToken.PacketTableHeader.len, 'Packet Table');
+        CafToken.decodePacketTableEntries(body, desc, packetTable.numberPackets);
+        this.packetTable = packetTable;
+    }
+    async readAudioData(chunkSize) {
+        if (chunkSize >= 0 && chunkSize < editCountLen) {
+            throw new CafContentError(`Audio Data chunk size ${chunkSize} is too small to hold mEditCount`);
+        }
+        if (chunkSize >= 0) {
+            this.validateChunkAvailability(chunkSize, 'Audio Data');
+        }
+        if ((await this.tokenizer.ignore(editCountLen)) !== editCountLen) {
+            throw new strtok3.EndOfStreamError();
+        }
+        if (chunkSize === -1) {
+            this.reachedEndOfFile = true; // Runs to the end of the file, nothing can follow
+            const { size } = this.tokenizer.fileInfo;
+            if (size === undefined) {
+                debug('Audio Data chunk has an unknown size, cannot derive the bitrate');
+                return;
+            }
+            this.dataBytes = size - this.tokenizer.position;
+            await this.tokenizer.ignore(this.dataBytes);
+            return;
+        }
+        const dataBytes = chunkSize - editCountLen;
+        if ((await this.tokenizer.ignore(dataBytes)) !== dataBytes) {
+            throw new strtok3.EndOfStreamError();
+        }
+        this.dataBytes = dataBytes;
+    }
+    async readInfo(chunkSize) {
+        if (chunkSize < numEntriesLen) {
+            throw new CafContentError(`Information chunk size ${chunkSize} is too small to hold mNumEntries`);
+        }
+        const body = await this.readChunkBody(chunkSize, 'Information');
+        for (const { key, value } of CafToken.parseInfoEntries(body)) {
+            debug(`info key=${key}`);
+            await this.metadata.addTag('CAF', key, value);
+        }
+    }
+    async readChannelLayout(chunkSize) {
+        if (chunkSize < CafToken.ChannelLayoutHeader.len) {
+            throw new CafContentError(`Channel Layout chunk size ${chunkSize} is smaller than ${CafToken.ChannelLayoutHeader.len}`);
+        }
+        this.validateChunkAvailability(chunkSize, 'Channel Layout');
+        const header = await this.tokenizer.readToken(CafToken.ChannelLayoutHeader);
+        const descriptionLen = header.numberChannelDescriptions * CafToken.channelDescriptionLen;
+        const bodyLen = CafToken.ChannelLayoutHeader.len + descriptionLen;
+        if (bodyLen > chunkSize) {
+            throw new CafContentError(`Channel Layout chunk declares ${header.numberChannelDescriptions} description(s) which exceed its size of ${chunkSize}`);
+        }
+        const descriptions = descriptionLen > 0
+            ? CafToken.parseChannelDescriptions(await this.readChunkBody(descriptionLen, 'Channel Layout'), header.numberChannelDescriptions)
+            : [];
+        await this.addChannelLayout(header, descriptions);
+        await this.tokenizer.ignore(chunkSize - bodyLen);
+    }
+    async addChannelLayout(header, descriptions) {
+        await this.metadata.addTag('CAF', 'channelLayoutTag', header.channelLayoutTag);
+        await this.metadata.addTag('CAF', 'channelLayoutBitmap', header.channelBitmap);
+        if (descriptions.length > 0) {
+            // No common tag describes channel order so keep the complete descriptions
+            await this.metadata.addTag('CAF', 'channelLayoutDescriptions', descriptions);
+        }
+    }
+    /**
+     * Rejects a whole chunk whose declared size exceeds the remaining input.
+     * Only applicable when the total input size is known.
+     */
+    validateChunkAvailability(chunkSize, chunkType) {
+        const { size } = this.tokenizer.fileInfo;
+        if (size !== undefined) {
+            const available = size - this.tokenizer.position;
+            if (chunkSize > available) {
+                throw new CafContentError(`${chunkType} chunk size ${chunkSize} exceeds available input size ${available}`);
+            }
+        }
+    }
+    /**
+     * Reads a chunk body without trusting its declared size.
+     * @param chunkSize Declared body size
+     * @param chunkType Chunk name for error messages
+     */
+    async readChunkBody(chunkSize, chunkType) {
+        this.validateChunkAvailability(chunkSize, chunkType);
+        return this.readToken(new Token.Uint8ArrayType(chunkSize));
+    }
+    async skipUnknownChunk(chunkSize) {
+        if (chunkSize < 0) {
+            throw new CafContentError(`Chunk size ${chunkSize} may only be -1 for an Audio Data chunk`);
+        }
+        await this.tokenizer.ignore(chunkSize);
+    }
+    // Deferred: the packet table and audio payload may arrive after the description
+    applyDerivedFormat() {
+        const desc = this.desc;
+        if (!desc || desc.sampleRate <= 0) {
+            return;
+        }
+        const frames = this.deriveFrameCount(desc);
+        if (frames === undefined) {
+            debug('Unable to derive the number of sample frames');
+            return;
+        }
+        const duration = frames / desc.sampleRate;
+        this.metadata.setFormat('numberOfSamples', frames);
+        this.metadata.setFormat('duration', duration);
+        if (this.dataBytes !== undefined) {
+            this.metadata.setFormat('bitrate', (8 * this.dataBytes) / duration);
+        }
+    }
+    deriveFrameCount(desc) {
+        const packetTable = this.packetTable;
+        if (packetTable) {
+            // Signed field, writers emit negative values. Already excludes priming and remainder frames.
+            if (packetTable.numberValidFrames > 0) {
+                return packetTable.numberValidFrames;
+            }
+            debug(`Ignoring packet table with mNumberValidFrames=${packetTable.numberValidFrames}`);
+        }
+        if (desc.bytesPerPacket > 0 && desc.framesPerPacket > 0 && this.dataBytes !== undefined) {
+            const frames = (this.dataBytes * desc.framesPerPacket) / desc.bytesPerPacket;
+            if (frames > 0) {
+                return frames;
+            }
+        }
+        return undefined;
+    }
+}

package/lib/caf/CafTagMap.d.ts

@@ -0,0 +1,8 @@
+import { CommonTagMapper } from '../common/GenericTagMapper.js';
+import type { IGenericTag } from '../common/GenericTagTypes.js';
+import type { IWarningCollector } from '../common/MetadataCollector.js';
+import type { ITag } from '../type.js';
+export declare class CafTagMapper extends CommonTagMapper {
+    constructor();
+    mapGenericTag(tag: ITag, warnings: IWarningCollector): IGenericTag | null;
+}

package/lib/caf/CafTagMap.js

@@ -0,0 +1,38 @@
+import { CommonTagMapper } from '../common/GenericTagMapper.js';
+// "time signature", "nominal bit rate" and "channel layout" have no common
+// equivalent and stay native. Undocumented keys are always kept natively too.
+const infoTagMap = {
+    tempo: 'bpm',
+    'key signature': 'key',
+    artist: 'artist',
+    album: 'album',
+    'track number': 'track',
+    year: 'year',
+    composer: 'composer',
+    lyricist: 'lyricist',
+    genre: 'genre',
+    title: 'title',
+    'recorded date': 'date',
+    comments: 'comment',
+    copyright: 'copyright',
+    'source encoder': 'encodersettings',
+    'encoding application': 'encodedby'
+};
+const commaSeparatedKeys = new Set(['artist', 'composer', 'lyricist', 'genre']);
+export class CafTagMapper extends CommonTagMapper {
+    constructor() {
+        super(['CAF'], infoTagMap);
+    }
+    mapGenericTag(tag, warnings) {
+        if (commaSeparatedKeys.has(tag.id) && typeof tag.value === 'string') {
+            tag = {
+                id: tag.id,
+                value: tag.value
+                    .split(',')
+                    .map(value => value.trim())
+                    .filter(value => value.length > 0)
+            };
+        }
+        return super.mapGenericTag(tag, warnings);
+    }
+}

package/lib/caf/CafToken.d.ts

@@ -0,0 +1,75 @@
+import type { IGetToken } from 'strtok3';
+declare const CafContentError_base: {
+    new (message: string): {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        name: "UnexpectedFileContentError";
+        readonly fileType: string;
+        toString(): string;
+    };
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+export declare class CafContentError extends CafContentError_base {
+}
+export interface ICafFileHeader {
+    fileType: string;
+    fileVersion: number;
+    fileFlags: number;
+}
+export declare const FileHeader: IGetToken<ICafFileHeader>;
+export interface ICafChunkHeader {
+    chunkType: string;
+    /** Size of the data section, -1 if the Audio Data chunk runs to the end of file */
+    chunkSize: number;
+}
+export declare const ChunkHeader: IGetToken<ICafChunkHeader>;
+export interface IAudioDescription {
+    sampleRate: number;
+    formatId: string;
+    formatFlags: number;
+    bytesPerPacket: number;
+    framesPerPacket: number;
+    channelsPerFrame: number;
+    bitsPerChannel: number;
+}
+/** CAFAudioFormat: Float64 mSampleRate followed by six UInt32 fields */
+export declare const AudioDescription: IGetToken<IAudioDescription>;
+export interface IPacketTableHeader {
+    numberPackets: number;
+    numberValidFrames: number;
+    primingFrames: number;
+    remainderFrames: number;
+}
+/** Fixed 24 byte part of a Packet Table chunk */
+export declare const PacketTableHeader: IGetToken<IPacketTableHeader>;
+/**
+ * Decodes the base-128, MSB-first integers that follow a Packet Table header,
+ * high-order bit set meaning the number continues in the next byte.
+ * @returns number of bytes occupied by the entries
+ */
+export declare function decodePacketTableEntries(body: Uint8Array, desc: IAudioDescription, numberPackets: number): number;
+export interface IChannelLayoutHeader {
+    channelLayoutTag: number;
+    channelBitmap: number;
+    numberChannelDescriptions: number;
+}
+/** Leading 12 bytes of a Channel Layout chunk, mChannelBitmap is always present */
+export declare const ChannelLayoutHeader: IGetToken<IChannelLayoutHeader>;
+export interface IChannelDescription {
+    channelLabel: number;
+    channelFlags: number;
+    coordinates: [number, number, number];
+}
+export declare const channelDescriptionLen = 20;
+/** Each CAFChannelDescription has a UInt32 label, UInt32 flags and three Float32 coordinates */
+export declare function parseChannelDescriptions(body: Uint8Array, count: number): IChannelDescription[];
+export interface IInfoEntry {
+    key: string;
+    value: string;
+}
+/** Reads the NUL terminated UTF-8 pairs, the declared entry count is authoritative */
+export declare function parseInfoEntries(body: Uint8Array): IInfoEntry[];
+export {};