taglib-wasm 2.2.3 → 2.3.0

package/dist/src/taglib/audio-file-checksum.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview `mediaChecksum()`: a SHA-256 of a file's *encoded media
+ * payload* — the bytes that are the audio, and not the tags around them — plus
+ * FLAC's STREAMINFO digest passthrough. Factored out of `AudioFileImpl` so the
+ * source rule below (what actually gets hashed) is stated exactly once.
+ */
+import type { PlatformIO } from "../runtime/platform-io.js";
+export type MediaChecksum = {
+    source: "audio-payload" | "file";
+    algorithm: "sha256";
+    hex: string;
+    bytesHashed: number;
+} | {
+    source: "flac-streaminfo-md5";
+    algorithm: "md5";
+    hex: string;
+    bytesHashed: 16;
+};
+export interface MediaChecksumOptions {
+    basis?: "encoded" | "pcm";
+}
+/** The literal a checksum's `source` field carries, so a consumer can hold one
+ * without restating the values. */
+export type ChecksumSource = MediaChecksum["source"];
+/** The algorithm any returned checksum can carry — narrowed by `source`. */
+export type ChecksumAlgorithm = MediaChecksum["algorithm"];
+/**
+ * What the checksum needs from the open handle — module-internal, and not
+ * re-exported from either entry point (`ChecksumSource` above is the public name,
+ * and a handle descriptor must not shadow it).
+ */
+interface ChecksumHandleSource {
+    /** The bytes the handle holds — a full file, a partial-load window image, or
+     * nothing at all when the data lives on disk (WASI path mode). */
+    bytes: Uint8Array;
+    /** The path, when the handle was opened from one. */
+    path?: string;
+    /** The File/Blob, when the handle was opened from one. */
+    blob?: Blob;
+    /** True when `bytes` is a spliced header+footer image rather than the file.
+     * Must be captured when the handle is created: `saveToFile()` clears the
+     * instance's own flag while the bytes stay spliced. */
+    partiallyLoaded: boolean;
+}
+export declare function mediaChecksum(source: ChecksumHandleSource, format: string, io: PlatformIO, options?: MediaChecksumOptions): Promise<MediaChecksum>;
+export {};
+//# sourceMappingURL=audio-file-checksum.d.ts.map

package/dist/src/taglib/audio-file-checksum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-file-checksum.d.ts","sourceRoot":"","sources":["../../../src/taglib/audio-file-checksum.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D,MAAM,MAAM,aAAa,GACrB;IACA,MAAM,EAAE,eAAe,GAAG,MAAM,CAAC;IACjC,SAAS,EAAE,QAAQ,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB,GACC;IACA,MAAM,EAAE,qBAAqB,CAAC;IAC9B,SAAS,EAAE,KAAK,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,EAAE,CAAC;CACjB,CAAC;AAEJ,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;CAC3B;AAED;mCACmC;AACnC,MAAM,MAAM,cAAc,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;AAErD,4EAA4E;AAC5E,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;AAE3D;;;;GAIG;AACH,UAAU,oBAAoB;IAC5B;sEACkE;IAClE,KAAK,EAAE,UAAU,CAAC;IAClB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;2DAEuD;IACvD,eAAe,EAAE,OAAO,CAAC;CAC1B;AA6FD,wBAAsB,aAAa,CACjC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,UAAU,EACd,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CAoExB"}

package/dist/src/taglib/audio-file-checksum.js

@@ -0,0 +1,77 @@
+import { flacStreamInfoMd5, mediaRanges } from "./media-ranges.js";
+import { MetadataError, UnsupportedFormatError } from "../errors.js";
+const STREAMINFO_WINDOW = 65536;
+async function fileBytes(source, io) {
+  if (source.path) return await io.readFile(source.path);
+  if (source.blob) return new Uint8Array(await source.blob.arrayBuffer());
+  if (!source.partiallyLoaded && source.bytes.length > 0) return source.bytes;
+  throw new MetadataError(
+    "read",
+    "the handle holds no file bytes and has no readable source; a partial handle that has been saved drops its source \u2014 checksum the saved path instead"
+  );
+}
+function joinRanges(bytes, ranges) {
+  const total = ranges.reduce((n, r) => n + r.length, 0);
+  const overrun = ranges.find((r) => r.offset + r.length > bytes.length);
+  if (overrun || total > bytes.length) {
+    throw new MetadataError(
+      "read",
+      `range walk overran the buffer (${overrun ? `range ${overrun.offset}+${overrun.length}` : `${total} bytes`} past the ${bytes.length}-byte buffer)`
+    );
+  }
+  if (ranges.length === 1) {
+    const only = ranges[0];
+    const view = bytes.subarray(only.offset, only.offset + only.length);
+    return view.buffer instanceof ArrayBuffer ? view : new Uint8Array(view);
+  }
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const r of ranges) {
+    out.set(bytes.subarray(r.offset, r.offset + r.length), at);
+    at += r.length;
+  }
+  return out;
+}
+async function mediaChecksum(source, format, io, options = {}) {
+  if (options.basis === "pcm") {
+    if (format.toUpperCase() !== "FLAC") {
+      throw new UnsupportedFormatError(format, ["FLAC"], {
+        operation: "media checksum (basis: pcm)"
+      });
+    }
+    const windowed = source.bytes.length > 0 ? source.bytes : source.path && io.readPartial ? await io.readPartial(source.path, STREAMINFO_WINDOW, 0) : void 0;
+    let md5 = windowed === void 0 ? void 0 : flacStreamInfoMd5(windowed);
+    if (md5 === void 0 && windowed !== source.bytes) {
+      md5 = flacStreamInfoMd5(await fileBytes(source, io));
+    }
+    if (md5 === void 0) {
+      throw new MetadataError(
+        "read",
+        "STREAMINFO digest unavailable"
+      );
+    }
+    return {
+      source: "flac-streaminfo-md5",
+      algorithm: "md5",
+      hex: md5,
+      bytesHashed: 16
+    };
+  }
+  const bytes = await fileBytes(source, io);
+  const walk = mediaRanges(format, bytes);
+  const payload = joinRanges(bytes, walk.ranges);
+  const digest = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", payload)
+  );
+  let hex = "";
+  for (const byte of digest) hex += byte.toString(16).padStart(2, "0");
+  return {
+    source: walk.kind === "ranges" ? "audio-payload" : "file",
+    algorithm: "sha256",
+    hex,
+    bytesHashed: payload.length
+  };
+}
+export {
+  mediaChecksum
+};

package/dist/src/taglib/audio-file-impl.d.ts

@@ -6,6 +6,7 @@ import type { Id3v2Frame, Rating, UnsyncedLyrics } from "../constants/complex-pr
 import { type NormalizedRating } from "../utils/rating.js";
 import type { AudioFile } from "./audio-file-interface.js";
 import { BaseAudioFileImpl } from "./audio-file-base.js";
+import { type MediaChecksum, type MediaChecksumOptions } from "./audio-file-checksum.js";
 /** @internal Exported for unit tests (tests/node-fs-acquisition.test.ts). */
 export declare function readFileSync(path: string): Uint8Array;
 /**
@@ -16,9 +17,12 @@ export declare function readFileSync(path: string): Uint8Array;
  */
 export declare class AudioFileImpl extends BaseAudioFileImpl implements AudioFile {
     private pathModeBuffer;
+    /** How the handle was loaded — `isPartiallyLoaded` is mutated by saveToFile(). */
+    private readonly partiallyLoadedAtConstruction;
     constructor(module: TagLibModule, fileHandle: WasmFileHandle, sourcePath?: string, originalSource?: string | Uint8Array | ArrayBuffer | File, isPartiallyLoaded?: boolean, partialLoadOptions?: OpenOptions);
     save(): boolean;
     getFileBuffer(): Uint8Array;
+    mediaChecksum(options?: MediaChecksumOptions): Promise<MediaChecksum>;
     saveToFile(path?: string): Promise<void>;
     getPictures(): Picture[];
     setPictures(pictures: Picture[]): void;

package/dist/src/taglib/audio-file-impl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audio-file-impl.d.ts","sourceRoot":"","sources":["../../../src/taglib/audio-file-impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAIV,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,OAAO,KAAK,EACV,UAAU,EACV,MAAM,EACN,cAAc,EACf,MAAM,oCAAoC,CAAC;AAc5C,OAAO,EAAc,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAoBzD,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CASrD;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,iBAAkB,YAAW,SAAS;IACvE,OAAO,CAAC,cAAc,CAA2B;gBAG/C,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,cAAc,EAC1B,UAAU,CAAC,EAAE,MAAM,EACnB,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,IAAI,EACzD,iBAAiB,GAAE,OAAe,EAClC,kBAAkB,CAAC,EAAE,WAAW;IAYlC,IAAI,IAAI,OAAO;IAef,aAAa,IAAI,UAAU;IA2BrB,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4D9C,WAAW,IAAI,OAAO,EAAE;IAYxB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI;IAStC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IASlC,cAAc,IAAI,IAAI;IAItB,WAAW,IAAI,OAAO,EAAE;IAqBxB,WAAW,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,IAAI;IA0BpE,OAAO,IAAI,uBAAuB,GAAG,SAAS;IAI9C,OAAO,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI;IAI5C,WAAW,IAAI,UAAU,GAAG,SAAS;IAIrC,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI;IAI1C,OAAO,IAAI,MAAM,GAAG,SAAS;IAI7B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIlC,UAAU,IAAI,MAAM,EAAE;IAWtB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAQnC,SAAS,IAAI,cAAc,EAAE;IAS7B,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI;IAQzC,SAAS,IAAI,gBAAgB,GAAG,SAAS;IAKzC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ/C,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAMzC,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI;IAOpD,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMnC,UAAU,IAAI;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE;IAI1C,YAAY,CAAC,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,EAAE,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;CAM1D"}
+{"version":3,"file":"audio-file-impl.d.ts","sourceRoot":"","sources":["../../../src/taglib/audio-file-impl.ts"],"names":[],"mappings":"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"}

package/dist/src/taglib/audio-file-impl.js

@@ -19,6 +19,10 @@ import { getNodeFsSync } from "../utils/node-fs.js";
 import { normalized } from "../utils/rating.js";
 import { isDeno } from "../runtime/detector.js";
 import { BaseAudioFileImpl } from "./audio-file-base.js";
+import {
+  mediaChecksum
+} from "./audio-file-checksum.js";
+import { getPlatformIO } from "../runtime/platform-io.js";
 import { saveViaFreshHandle } from "./save-reconstruct.js";
 function sortChapters(list) {
   return [...list].sort((a, b) => a.startTimeMs - b.startTimeMs);
@@ -50,6 +54,9 @@ class AudioFileImpl extends BaseAudioFileImpl {
       partialLoadOptions
     );
     __publicField(this, "pathModeBuffer", null);
+    /** How the handle was loaded — `isPartiallyLoaded` is mutated by saveToFile(). */
+    __publicField(this, "partiallyLoadedAtConstruction");
+    this.partiallyLoadedAtConstruction = isPartiallyLoaded;
   }
   save() {
     if (this.isPartiallyLoaded && this.originalSource) {
@@ -85,6 +92,31 @@ class AudioFileImpl extends BaseAudioFileImpl {
       "No file data available: in-memory buffer is empty and no source path is set"
     );
   }
+  mediaChecksum(options) {
+    return mediaChecksum(
+      {
+        // The cheap, no-IO accessor — `getFileBuffer()` would read the whole
+        // file from disk in path mode (and cache it), which the source rule is
+        // about to read for itself.
+        bytes: this.handle.getBuffer(),
+        // empty in path mode: the data is on disk
+        // Both optional fields are conditional: they are `undefined` far more
+        // often than not, and `exactOptionalPropertyTypes` refuses an explicit
+        // `undefined` on an optional property.
+        ...this.sourcePath !== void 0 ? { path: this.sourcePath } : {},
+        // originalSource is the File when the caller passed one. A partial File
+        // has no path, so this is the only way back to the real bytes.
+        ...this.originalSource instanceof Blob ? { blob: this.originalSource } : {},
+        // Captured at construction, NOT this.isPartiallyLoaded: saveToFile() sets
+        // that flag false (and clears originalSource) while the handle still holds
+        // the spliced image, which would make the source rule hash the image.
+        partiallyLoaded: this.partiallyLoadedAtConstruction
+      },
+      this.getFormat(),
+      getPlatformIO(),
+      options
+    );
+  }
   async saveToFile(path) {
     const targetPath = path ?? this.sourcePath;
     if (!targetPath) {

package/dist/src/taglib/audio-file-interface.d.ts

@@ -2,6 +2,7 @@ import type { AudioProperties, FileType, Picture, PropertyMap } from "../types.j
 import type { TypedAudioProperties } from "../types/audio-formats.js";
 import type { Id3v2Frame, Rating, UnsyncedLyrics } from "../constants/complex-properties.js";
 import type { MutableTag } from "./mutable-tag.js";
+import type { MediaChecksum, MediaChecksumOptions } from "./audio-file-checksum.js";
 import type { FormatPropertyKey } from "../types/format-property-keys.js";
 import type { NormalizedRating } from "../utils/rating.js";
 /**
@@ -66,6 +67,22 @@ export interface AudioFile {
      * and cannot be read back — never returns an empty buffer on failure.
      */
     getFileBuffer(): Uint8Array;
+    /**
+     * SHA-256 of the file's encoded media payload — the bytes that are the audio,
+     * not the tags around them — so the digest survives a tag edit, with one
+     * boundary: an ID3v2 tag appended after a FLAC's audio is inside the payload,
+     * so editing it does move the hash. Formats whose payload cannot be delimited
+     * answer the whole file instead and say so (`source: "file"`), where a tag
+     * edit does move the hash.
+     *
+     * Pass `{ basis: "pcm" }` for FLAC's STREAMINFO MD5 — the digest of the
+     * *uncompressed* stream, read straight from the file's first metadata block.
+     * Other formats throw {@link UnsupportedFormatError}.
+     *
+     * @throws {MetadataError} If the handle holds no file bytes and has no
+     * readable source (a partial handle that has already been saved).
+     */
+    mediaChecksum(options?: MediaChecksumOptions): Promise<MediaChecksum>;
     /**
      * Save all changes to a file on disk.
      * @param path - Optional file path. If not provided, saves to the original path.

package/dist/src/taglib/audio-file-interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audio-file-interface.d.ts","sourceRoot":"","sources":["../../../src/taglib/audio-file-interface.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"audio-file-interface.d.ts","sourceRoot":"","sources":["../../../src/taglib/audio-file-interface.ts"],"names":[],"mappings":"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"}

package/dist/src/taglib/media-ranges.d.ts

@@ -0,0 +1,85 @@
+export interface ByteRange {
+    offset: number;
+    length: number;
+}
+export interface RangeWalk {
+    kind: "ranges" | "fallback";
+    ranges: ByteRange[];
+    detail: string;
+}
+/**
+ * Start offset of a trailing tag run (ID3v1 and/or APEv2), scanning inward.
+ * TagLib ends a FLAC stream at its ID3v1 location for the same reason.
+ */
+export declare function trailingTagStart(bytes: Uint8Array, end?: number): number;
+export declare function walkMpeg(bytes: Uint8Array): RangeWalk;
+/** STREAMINFO is a FLAC file's first metadata block: the `fLaC` marker, a
+ * 4-byte block header, then its 34-byte payload, whose last 16 bytes are the
+ * MD5 of the *uncompressed* stream — the digest `basis: "pcm"` reports. */
+export declare function flacStreamInfoMd5(bytes: Uint8Array): string | undefined;
+/**
+ * FLAC's encoded payload: the audio frames between the end of the metadata
+ * block chain and an appended ID3v1/APEv2 tag. An appended ID3v2 is *inside*
+ * the payload: TagLib ends a FLAC stream at its ID3v1 location
+ * (`flacfile.cpp:595-599`), and a tag not at that location is stream by the
+ * same rule — TagLib is this feature's ground truth, so the boundary is pinned
+ * by `tests/media-ranges.test.ts`, not "fixed" here. Nothing inside a FLAC
+ * stream delimits the frames — the block chain's end is the start, and the
+ * stream runs to EOF — so the whole rule is the block walk plus the
+ * trailing-tag trim.
+ *
+ * `flacAudioStart` may legitimately answer past `bytes.length`, because a
+ * block's declared length can reach beyond the bytes in hand: that is the
+ * extent the chain *implies*, and hashing it would read nothing while claiming
+ * a payload. The `end <= start` guard is what refuses it.
+ *
+ * The walk deliberately does **not** carry the STREAMINFO digest: a range result
+ * is not a digest carrier, and the PCM basis reads the digest with
+ * `flacStreamInfoMd5` directly. A second, unread path to the same value rots.
+ */
+export declare function walkFlac(bytes: Uint8Array): RangeWalk;
+/**
+ * MP4's payload: the contents of every non-empty top-level `mdat`, in file
+ * order — a fragmented file spreads its audio over several, and a rewritten one
+ * may carry an empty `mdat`, which is legal and contributes nothing. The header
+ * is excluded, and it is 16 bytes rather than 8 when the size took the 64-bit
+ * form.
+ *
+ * Deliberately not `metadata-extent.ts`'s atom walk: that one looks for `moov`
+ * to size the partial-load gate, so it bails on any size below 8 and has no
+ * 64-bit path. The checksum's rules differ — `size === 0` runs to EOF, a 64-bit
+ * size is legal, and anything the walk cannot fully account for is a fallback —
+ * so the two contracts stay apart rather than share an abstraction.
+ *
+ * Those fallbacks are the point. A range that runs past the buffer would hash
+ * zero padding while `bytesHashed` counts it as payload, and bytes no atom
+ * accounts for are not something this walk may call audio.
+ */
+export declare function walkMp4(bytes: Uint8Array): RangeWalk;
+/**
+ * WAV's payload: every non-empty `data` chunk's contents, payload only.
+ *
+ * The chunk list is the whole rule: a chunk is a 4-byte id, a 4-byte
+ * little-endian size that counts the payload but not the header, and that
+ * payload padded to an even length. Tag chunks (`LIST`, `id3 `, `bext`, `iXML`)
+ * are therefore skipped by construction rather than by name, and chunks that
+ * follow `data` cannot move or clip the range — which is the property the
+ * repo's `wav/kiss-snippet.wav` pins, `data` first and `LIST` + `id3 ` behind it.
+ *
+ * A chunk whose declared size reaches past the buffer is a fallback, not a
+ * clamp: hashing the bytes that survive would report a payload the file does not
+ * claim. That is also the truncated-file case.
+ */
+export declare function walkWav(bytes: Uint8Array): RangeWalk;
+/**
+ * The per-format dispatch: the one entry point a consumer calls, and the one
+ * place a format-level fallback becomes a whole-file range.
+ *
+ * Consumers MUST dispatch on `kind`, never on `ranges.length`. The walks
+ * themselves answer a fallback with `ranges: []`, which this function replaces
+ * with the whole file — so after normalization there is no empty-ranges answer
+ * to detect, and a caller testing `ranges.length === 0` would read a fallback as
+ * a genuine payload and hash the whole file while claiming a range.
+ */
+export declare function mediaRanges(format: string, bytes: Uint8Array): RangeWalk;
+//# sourceMappingURL=media-ranges.d.ts.map

package/dist/src/taglib/media-ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-ranges.d.ts","sourceRoot":"","sources":["../../../src/taglib/media-ranges.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAgCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,EACjB,GAAG,SAAe,GACjB,MAAM,CAoBR;AA8DD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAYrD;AAED;;2EAE2E;AAC3E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAmBvE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAUrD;AAqBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAyBpD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAsBpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,SAAS,CAgCxE"}

package/dist/src/taglib/media-ranges.js

@@ -0,0 +1,192 @@
+import {
+  flacAudioStart,
+  flacMarkerOffset,
+  id3v2End,
+  mpegFrameLength
+} from "./metadata-extent.js";
+const decoder = new TextDecoder();
+const text = (b, o, n) => decoder.decode(b.subarray(o, o + n));
+const fallback = (detail) => ({
+  kind: "fallback",
+  ranges: [],
+  detail
+});
+function adtsFrameLength(bytes, at) {
+  if (bytes.length < at + 7) return 0;
+  if (bytes[at] !== 255 || (bytes[at + 1] & 246) !== 240) return 0;
+  const length = (bytes[at + 3] & 3) << 11 | bytes[at + 4] << 3 | bytes[at + 5] >> 5;
+  return length >= 7 ? length : 0;
+}
+const frameLengthAt = (bytes, at) => mpegFrameLength(bytes, at) || adtsFrameLength(bytes, at);
+function trailingTagStart(bytes, end = bytes.length) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let at = Math.max(0, Math.min(end, bytes.length));
+  for (; ; ) {
+    if (at >= 128 && text(bytes, at - 128, 3) === "TAG") {
+      at -= 128;
+      continue;
+    }
+    if (at >= 32 && text(bytes, at - 32, 8) === "APETAGEX") {
+      const size = view.getUint32(at - 32 + 12, true);
+      const flags = view.getUint32(at - 32 + 20, true);
+      const start = at - size - ((flags & 2147483648) !== 0 ? 32 : 0);
+      if (start < 0 || start >= at) return at;
+      at = start;
+      continue;
+    }
+    return at;
+  }
+}
+const MPEG_SCAN_LIMIT = 65536;
+function firstFrame(bytes) {
+  const from = id3v2End(bytes) ?? 0;
+  const limit = Math.min(bytes.length - 6, from + MPEG_SCAN_LIMIT);
+  for (let o = from; o < limit; o++) {
+    const len = frameLengthAt(bytes, o);
+    if (len > 0 && frameLengthAt(bytes, o + len) > 0) return o;
+  }
+  return -1;
+}
+function forwardLastFrame(bytes, from, end) {
+  let o = from;
+  let start = -1;
+  let length = 0;
+  let frames = 0;
+  while (o + 6 <= end) {
+    const len = frameLengthAt(bytes, o);
+    if (len === 0 || o + len > end) break;
+    start = o;
+    length = len;
+    frames++;
+    o += len;
+  }
+  return { start, length, frames };
+}
+function walkMpeg(bytes) {
+  const from = firstFrame(bytes);
+  if (from < 0) return fallback("no valid first frame");
+  const end = trailingTagStart(bytes);
+  const last = forwardLastFrame(bytes, from, end);
+  if (last.start < 0) return fallback("no valid frames");
+  return {
+    kind: "ranges",
+    ranges: [{ offset: from, length: last.start + last.length - from }],
+    detail: `first=${from} last=${last.start}+${last.length} frames=${last.frames}`
+  };
+}
+function flacStreamInfoMd5(bytes) {
+  const marker = flacMarkerOffset(bytes);
+  if (marker === void 0) return void 0;
+  const header = marker + 4;
+  if (header + 4 > bytes.length) return void 0;
+  if ((bytes[header] & 127) !== 0) return void 0;
+  const blockLength = bytes[header + 1] << 16 | bytes[header + 2] << 8 | bytes[header + 3];
+  if (blockLength < 34) return void 0;
+  const payload = header + 4;
+  if (payload + 34 > bytes.length) return void 0;
+  let hex = "";
+  for (const byte of bytes.subarray(payload + 18, payload + 34)) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+function walkFlac(bytes) {
+  const start = flacAudioStart(bytes);
+  if (start === void 0) return fallback("no fLaC marker");
+  const end = trailingTagStart(bytes);
+  if (end <= start) return fallback("no audio bytes");
+  return {
+    kind: "ranges",
+    ranges: [{ offset: start, length: end - start }],
+    detail: `audioStart=${start} end=${end}`
+  };
+}
+function atomLength(bytes, view, o) {
+  const size = view.getUint32(o, false);
+  if (size === 0) return { length: bytes.length - o, headerSize: 8 };
+  if (size === 1) {
+    if (o + 16 > bytes.length) return void 0;
+    const big = view.getBigUint64(o + 8, false);
+    if (big > BigInt(Number.MAX_SAFE_INTEGER)) return void 0;
+    return { length: Number(big), headerSize: 16 };
+  }
+  return { length: size, headerSize: 8 };
+}
+function walkMp4(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const ranges = [];
+  let o = 0;
+  while (o + 8 <= bytes.length) {
+    const type = text(bytes, o + 4, 4);
+    const atom = atomLength(bytes, view, o);
+    if (atom === void 0) return fallback(`malformed ${type} size`);
+    if (atom.length < atom.headerSize) {
+      return fallback(`malformed ${type} size`);
+    }
+    if (o + atom.length > bytes.length) return fallback(`oversized ${type}`);
+    if (type === "mdat" && atom.length > atom.headerSize) {
+      ranges.push({
+        offset: o + atom.headerSize,
+        length: atom.length - atom.headerSize
+      });
+    }
+    o += atom.length;
+  }
+  if (o !== bytes.length) return fallback("trailing bytes after the last atom");
+  if (ranges.length === 0) return fallback("no non-empty mdat");
+  return { kind: "ranges", ranges, detail: `${ranges.length} mdat(s)` };
+}
+function walkWav(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (text(bytes, 0, 4) !== "RIFF") return fallback("not RIFF");
+  if (text(bytes, 8, 4) !== "WAVE") return fallback("not WAVE");
+  const ranges = [];
+  let o = 12;
+  while (o + 8 <= bytes.length) {
+    const id = text(bytes, o, 4);
+    const size = view.getUint32(o + 4, true);
+    const dataStart = o + 8;
+    if (dataStart + size > bytes.length) return fallback(`truncated ${id}`);
+    if (id === "data" && size > 0) {
+      ranges.push({ offset: dataStart, length: size });
+    }
+    o = dataStart + size + size % 2;
+  }
+  if (ranges.length === 0) return fallback("no data chunk");
+  return { kind: "ranges", ranges, detail: `${ranges.length} data chunk(s)` };
+}
+function mediaRanges(format, bytes) {
+  const walked = (() => {
+    switch (format.toUpperCase()) {
+      case "MP3":
+      case "AAC":
+        return walkMpeg(bytes);
+      case "FLAC":
+        return walkFlac(bytes);
+      case "MP4":
+      case "M4A":
+        return walkMp4(bytes);
+      case "WAV":
+        return walkWav(bytes);
+      default:
+        return { kind: "fallback", ranges: [], detail: "format not covered" };
+    }
+  })();
+  if (walked.kind === "fallback") {
+    return {
+      kind: "fallback",
+      ranges: [{ offset: 0, length: bytes.length }],
+      detail: `${walked.detail} \u2192 whole file`
+    };
+  }
+  return walked;
+}
+export {
+  flacStreamInfoMd5,
+  mediaRanges,
+  trailingTagStart,
+  walkFlac,
+  walkMp4,
+  walkMpeg,
+  walkWav
+};

package/dist/src/taglib/metadata-extent.d.ts

@@ -14,7 +14,62 @@
  * asymmetric: return true ONLY when the metadata is provably contained. Anything
  * unrecognised, malformed, or unbounded answers false, which costs a full read
  * and never costs correctness.
+ *
+ * The container walkers themselves are exported (id3v2End, mpegFrameLength,
+ * flacAudioStart, flacMarkerOffset) because the media checksum walks the same
+ * containers to find a file's encoded-audio payload. One walker per container:
+ * a second copy of these rules could silently disagree with the one that
+ * decides whether a splice is safe.
+ */
+/**
+ * End of an ID3v2 tag at offset 0, or undefined when there is none.
+ *
+ * The size field is "syncsafe": seven bits per byte, so the high bit can never
+ * produce a false frame sync. A footer, when the flags say there is one, adds
+ * ten bytes that the size does not cover.
+ *
+ * The `ID3` magic check is part of the contract, not a convenience: the size
+ * arithmetic reads a number out of any ten bytes, so a tagless buffer would
+ * otherwise report 22.8 million as the end of a tag it does not have. Callers
+ * that have already established the magic pay one comparison for it; callers
+ * that have not (the media checksum walks) need it.
+ */
+export declare function id3v2End(bytes: Uint8Array): number | undefined;
+/**
+ * Offset of FLAC's `fLaC` stream marker — at 0, or just past a prepended ID3v2
+ * tag (TagLib supports exactly that, flacfile.cpp:90) — or undefined when
+ * neither is there. A caller that only wants STREAMINFO can seek straight to it
+ * instead of walking the metadata-block chain.
+ */
+export declare function flacMarkerOffset(bytes: Uint8Array): number | undefined;
+/**
+ * Offset of FLAC's first audio byte: the end of the metadata-block chain, past
+ * the optional ID3v2 tag.
+ *
+ * The chain is walked from block headers alone, so the result can exceed
+ * `bytes.length` when a block's declared length reaches past the buffer — that
+ * is the extent the chain implies, and the caller decides whether it holds
+ * enough of the file to believe it. A buffer too short to hold the next block
+ * header has no implied extent at all and answers undefined, as does one with
+ * no `fLaC` marker.
+ */
+export declare function flacAudioStart(bytes: Uint8Array): number | undefined;
+/**
+ * Length in bytes of the MPEG (Layer I/II/III) frame whose header sits at `at`,
+ * or 0 when `at` is not a plausible frame header.
+ *
+ * Plausibility is the header alone: eleven sync bits, a non-reserved version
+ * and layer, a bitrate index that is neither free (0) nor invalid (15), and a
+ * sample-rate index that is not reserved (3). Nothing here looks at what
+ * FOLLOWS the frame — a frame header at the very end of a file is as plausible
+ * as any other, which is what lets a walk reach the last frame. Callers that
+ * need confidence the bytes really are MPEG audio want isMpegFrameSync, which
+ * adds the next-header consistency check.
+ *
+ * The arithmetic mirrors mpegheader.cpp:236-264: bitrate/sample-rate tables
+ * plus the padding bit, and C++ integer division truncates.
  */
+export declare function mpegFrameLength(bytes: Uint8Array, at: number): number;
 /**
  * True only when the metadata of `header` provably ends within `limit` bytes.
  *

package/dist/src/taglib/metadata-extent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-extent.d.ts","sourceRoot":"","sources":["../../../src/taglib/metadata-extent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgPH;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAiCT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAmBT"}
+{"version":3,"file":"metadata-extent.d.ts","sourceRoot":"","sources":["../../../src/taglib/metadata-extent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAgBH;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAM9D;AA2BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAItE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAIpE;AAwGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CA8BrE;AA2DD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAiCT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAmBT"}