taglib-wasm 1.5.2 → 1.6.0

package/LICENSE

@@ -27,21 +27,24 @@ ADDITIONAL LICENSING INFORMATION:
 This product includes software developed by Scott Wheeler and the TagLib 
 contributors (https://taglib.org/).
 
-The WebAssembly binary (build/taglib.wasm) contains compiled TagLib code
-which is licensed under LGPL-2.1-or-later. The original TagLib source code
-is located in lib/taglib/. See lib/taglib/COPYING.LGPL for the full LGPL
-license terms.
+The WebAssembly binaries (build/taglib-web.wasm for the Emscripten backend
+and build/taglib-wasi.wasm for the WASI backend, shipped as dist/*.wasm)
+contain compiled TagLib code which is licensed under LGPL-2.1-or-later.
+The original TagLib source code is located in lib/taglib/. See
+lib/taglib/COPYING.LGPL for the full LGPL license terms.
 
 LGPL COMPLIANCE:
-The WebAssembly binary is subject to LGPL requirements. This means:
-- You may use it in commercial applications
+The WebAssembly binaries are subject to LGPL requirements. This means:
+- You may use them in commercial applications
 - Modifications to TagLib must be shared under LGPL
 - You must enable users to relink with modified TagLib versions
 
-To rebuild the WebAssembly binary with a modified TagLib:
+To rebuild the WebAssembly binaries with a modified TagLib:
 1. Modify the TagLib source in lib/taglib/
-2. Run: npm run build:wasm
-3. The new binary will be in build/taglib.wasm
+2. Run: npm run build:wasm  (builds both backends; requires the
+   Emscripten SDK and WASI SDK 33 — see CONTRIBUTING.md)
+3. The new binaries will be in build/taglib-web.wasm and
+   build/taglib-wasi.wasm
 
 For more information about LGPL compliance and dual licensing, see:
 https://github.com/CharlesWiltgen/TagLib-Wasm#licensing

package/README.md

@@ -33,8 +33,11 @@ TagLib-Wasm is the **universal tagging library for TypeScript/JavaScript**
   possible
 - **Rich metadata** – Cover art, ratings, chapters (MP3 `CHAP`, MP4
   QuickTime/Nero), and broadcast metadata (BWF `bext`/iXML for WAV/FLAC)
+- **Value fidelity** – Tag values round-trip verbatim: a `"3/12"` track or a
+  zero-padded `"03"` is preserved, and MP4 freeform atoms keep their exact
+  casing and vendor `mean`, so other tools still recognise them
 - **Zero dependencies** – Self-contained Wasm bundle
-- **Tested** – 293 tests across all formats
+- **Tested** – 448 tests across all formats, with cross-backend parity coverage
 - **Two API styles** – Use the "Simple" API (3 functions), or the full "Core"
   API for more advanced applications
 - **Batch folder operations** – Scan directories, process multiple files, find
@@ -48,8 +51,8 @@ TagLib-Wasm is the **universal tagging library for TypeScript/JavaScript**
 npm install taglib-wasm
 ```
 
-> **Note:** Requires Node.js v22.6.0 or higher for WASI and WebAssembly
-> exception handling support. To consume the package as TypeScript source
+> **Note:** Requires Node.js v24 or higher (the Active LTS line) for WASI and
+> WebAssembly exception handling support. To consume the package as TypeScript source
 > (e.g., via `tsx`), see the
 > [installation guide](https://charleswiltgen.github.io/TagLib-Wasm/guide/installation.html).
 

package/dist/index.browser.js

@@ -1443,6 +1443,26 @@ var init_specialized_properties = __esm({
           vorbis: "ITUNNORM",
           mp4: "----:com.apple.iTunes:iTunNORM"
         }
+      },
+      /**
+       * Apple gapless-playback data (encoder delay, padding, original sample count).
+       *
+       * Exists so the two Apple freeform atoms are presented consistently: without
+       * it, `properties()` answered `appleSoundCheck` for iTunNORM but the raw
+       * uppercased `ITUNSMPB` for its sibling, because only one had an alias. The
+       * name mirrors `appleSoundCheck` — vendor-prefixed, feature-named rather than
+       * atom-named (tuneup-ibo).
+       */
+      appleGaplessInfo: {
+        key: "ITUNSMPB",
+        description: "Apple gapless playback data (encoder delay and padding)",
+        type: "string",
+        supportedFormats: ["ID3v2", "MP4", "Vorbis"],
+        mappings: {
+          id3v2: { frame: "TXXX", description: "iTunSMPB" },
+          vorbis: "ITUNSMPB",
+          mp4: "----:com.apple.iTunes:iTunSMPB"
+        }
       }
     };
   }
@@ -1452,6 +1472,17 @@ var init_specialized_properties = __esm({
 function toTagLibKey(key) {
   return _toTagLib[key] ?? key;
 }
+function mp4AtomWireKey(atom) {
+  return _mp4AtomToWireKey[atom];
+}
+function mp4FreeformAtomNames(wireKeys) {
+  const names = [];
+  for (const key of wireKeys) {
+    const atom = _mp4FreeformAtoms[key];
+    if (atom !== void 0) names.push(atom);
+  }
+  return names;
+}
 function fromTagLibKey(key) {
   return _fromTagLib[key] ?? key;
 }
@@ -1462,7 +1493,7 @@ function remapKeysFromTagLib(obj) {
   }
   return result;
 }
-var PROPERTIES, _toTagLib, _fromTagLib;
+var PROPERTIES, _toTagLib, _fromTagLib, _mp4FreeformAtoms, _mp4AtomToWireKey;
 var init_properties = __esm({
   "src/constants/properties.ts"() {
     "use strict";
@@ -1486,6 +1517,129 @@ var init_properties = __esm({
     _toTagLib["year"] = "DATE";
     _toTagLib["track"] = "TRACKNUMBER";
     _fromTagLib["disc"] = "discNumber";
+    _mp4FreeformAtoms = {};
+    for (const meta of Object.values(PROPERTIES)) {
+      const { key, mappings } = meta;
+      const atom = mappings?.mp4;
+      if (typeof atom !== "string" || !atom.startsWith("----:")) continue;
+      const bare = atom.slice(atom.lastIndexOf(":") + 1);
+      if (bare === bare.toUpperCase()) continue;
+      _mp4FreeformAtoms[key] = atom;
+      const readKey = bare.toUpperCase();
+      const camel = _fromTagLib[key];
+      if (camel !== void 0 && _fromTagLib[readKey] === void 0) {
+        _fromTagLib[readKey] = camel;
+      }
+    }
+    _mp4AtomToWireKey = {};
+    for (const meta of Object.values(PROPERTIES)) {
+      const { key, mappings } = meta;
+      const atom = mappings?.mp4;
+      if (typeof atom !== "string" || atom.startsWith("----:")) continue;
+      if (_mp4AtomToWireKey[atom] === void 0) _mp4AtomToWireKey[atom] = key;
+    }
+  }
+});
+
+// src/taglib/mp4-item-names.ts
+var MP4_ITEM_NAMES_KEY;
+var init_mp4_item_names = __esm({
+  "src/taglib/mp4-item-names.ts"() {
+    "use strict";
+    MP4_ITEM_NAMES_KEY = "_mp4ItemNames";
+  }
+});
+
+// src/taglib/mutable-tag-impl.ts
+function buildMutableTag(handle) {
+  let data = handle.getTagData();
+  const tag = {
+    get title() {
+      return data.title;
+    },
+    get artist() {
+      return data.artist;
+    },
+    get album() {
+      return data.album;
+    },
+    get comment() {
+      return data.comment;
+    },
+    get genre() {
+      return data.genre;
+    },
+    get year() {
+      return data.year;
+    },
+    get track() {
+      return data.track;
+    },
+    get date() {
+      return handle.getProperty("DATE") || void 0;
+    },
+    setTitle: (value) => {
+      handle.setTagData({ title: value });
+      data = handle.getTagData();
+      return tag;
+    },
+    setArtist: (value) => {
+      handle.setTagData({ artist: value });
+      data = handle.getTagData();
+      return tag;
+    },
+    setAlbum: (value) => {
+      handle.setTagData({ album: value });
+      data = handle.getTagData();
+      return tag;
+    },
+    setComment: (value) => {
+      handle.setTagData({ comment: value });
+      data = handle.getTagData();
+      return tag;
+    },
+    setGenre: (value) => {
+      handle.setTagData({ genre: value });
+      data = handle.getTagData();
+      return tag;
+    },
+    setYear: (value) => {
+      handle.setTagData({ year: value });
+      data = handle.getTagData();
+      return tag;
+    },
+    setTrack: (value) => {
+      const existing = value > 0 ? handle.getProperty(RAW_TRACK_WIRE_KEY) : "";
+      const slash = existing.indexOf("/");
+      if (slash !== -1) {
+        handle.setProperty(
+          RAW_TRACK_WIRE_KEY,
+          `${value}${existing.slice(slash)}`
+        );
+      } else {
+        handle.setTagData({ track: value });
+      }
+      data = handle.getTagData();
+      return tag;
+    },
+    setDate: (value) => {
+      if (value === "") {
+        handle.setTagData({ year: 0 });
+      } else {
+        handle.setProperty("DATE", value);
+      }
+      data = handle.getTagData();
+      return tag;
+    }
+  };
+  return tag;
+}
+var RAW_TRACK_WIRE_KEY;
+var init_mutable_tag_impl = __esm({
+  "src/taglib/mutable-tag-impl.ts"() {
+    "use strict";
+    init_properties();
+    RAW_TRACK_WIRE_KEY = toTagLibKey("trackNumber");
   }
 });
 
@@ -1496,6 +1650,8 @@ var init_audio_file_base = __esm({
     "use strict";
     init_properties();
     init_errors2();
+    init_mp4_item_names();
+    init_mutable_tag_impl();
     LYRICS_PROPERTY_KEY = "lyrics";
     LYRICS_WIRE_KEY = toTagLibKey(LYRICS_PROPERTY_KEY);
     EMPTY_KEY_SET = /* @__PURE__ */ new Set();
@@ -1546,79 +1702,7 @@ var init_audio_file_base = __esm({
         return this.getFormat() === format;
       }
       tag() {
-        const handle = this.handle;
-        let data = handle.getTagData();
-        const tag = {
-          get title() {
-            return data.title;
-          },
-          get artist() {
-            return data.artist;
-          },
-          get album() {
-            return data.album;
-          },
-          get comment() {
-            return data.comment;
-          },
-          get genre() {
-            return data.genre;
-          },
-          get year() {
-            return data.year;
-          },
-          get track() {
-            return data.track;
-          },
-          get date() {
-            return handle.getProperty("DATE") || void 0;
-          },
-          setTitle: (value) => {
-            handle.setTagData({ title: value });
-            data = handle.getTagData();
-            return tag;
-          },
-          setArtist: (value) => {
-            handle.setTagData({ artist: value });
-            data = handle.getTagData();
-            return tag;
-          },
-          setAlbum: (value) => {
-            handle.setTagData({ album: value });
-            data = handle.getTagData();
-            return tag;
-          },
-          setComment: (value) => {
-            handle.setTagData({ comment: value });
-            data = handle.getTagData();
-            return tag;
-          },
-          setGenre: (value) => {
-            handle.setTagData({ genre: value });
-            data = handle.getTagData();
-            return tag;
-          },
-          setYear: (value) => {
-            handle.setTagData({ year: value });
-            data = handle.getTagData();
-            return tag;
-          },
-          setTrack: (value) => {
-            handle.setTagData({ track: value });
-            data = handle.getTagData();
-            return tag;
-          },
-          setDate: (value) => {
-            if (value === "") {
-              handle.setTagData({ year: 0 });
-            } else {
-              handle.setProperty("DATE", value);
-            }
-            data = handle.getTagData();
-            return tag;
-          }
-        };
-        return tag;
+        return buildMutableTag(this.handle);
       }
       audioProperties() {
         if (!this.cachedAudioProperties) {
@@ -1640,14 +1724,29 @@ var init_audio_file_base = __esm({
           const existing = this.handle.getProperties()[LYRICS_WIRE_KEY];
           if (existing !== void 0) translated[LYRICS_WIRE_KEY] = existing;
         }
+        const atomNames = mp4FreeformAtomNames(Object.keys(translated));
+        if (atomNames.length > 0) translated[MP4_ITEM_NAMES_KEY] = atomNames;
         this.handle.setProperties(translated);
       }
       getProperty(key) {
         const value = this.handle.getProperty(toTagLibKey(key));
-        return value === "" ? void 0 : value;
+        if (value !== "") return value;
+        if (!this.isMP4()) return void 0;
+        const remapped = this.properties()[key]?.[0];
+        return remapped === "" ? void 0 : remapped;
       }
       setProperty(key, value) {
-        this.handle.setProperty(toTagLibKey(key), value);
+        const wireKey = toTagLibKey(key);
+        const atomNames = mp4FreeformAtomNames([wireKey]);
+        if (atomNames.length > 0 && this.isMP4()) {
+          this.handle.setProperties({
+            ...this.handle.getProperties(),
+            [wireKey]: [value],
+            [MP4_ITEM_NAMES_KEY]: atomNames
+          });
+          return;
+        }
+        this.handle.setProperty(wireKey, value);
       }
       isMP4() {
         return this.handle.isMP4();
@@ -1656,13 +1755,19 @@ var init_audio_file_base = __esm({
         if (!this.isMP4()) {
           throw new UnsupportedFormatError(this.getFormat(), ["MP4", "M4A"]);
         }
-        const value = this.handle.getMP4Item(key);
+        const wireKey = mp4AtomWireKey(key);
+        const value = wireKey !== void 0 ? this.handle.getProperty(wireKey) : this.handle.getMP4Item(key);
         return value === "" ? void 0 : value;
       }
       setMP4Item(key, value) {
         if (!this.isMP4()) {
           throw new UnsupportedFormatError(this.getFormat(), ["MP4", "M4A"]);
         }
+        const wireKey = mp4AtomWireKey(key);
+        if (wireKey !== void 0) {
+          this.handle.setProperty(wireKey, value);
+          return;
+        }
         this.handle.setMP4Item(key, value);
       }
       removeMP4Item(key) {
@@ -1945,6 +2050,8 @@ function copyEditedState(target, source, sourceComplete, deletedKeys) {
   target.setTagData(source.getTagData());
   const merged = sourceComplete ? source.getProperties() : { ...target.getProperties(), ...source.getProperties() };
   for (const key of deletedKeys) delete merged[key];
+  const atomNames = mp4FreeformAtomNames(Object.keys(merged));
+  if (atomNames.length > 0) merged[MP4_ITEM_NAMES_KEY] = atomNames;
   target.setProperties(merged);
   copyExtraState(target, source, sourceComplete);
 }
@@ -1980,6 +2087,8 @@ var init_save_reconstruct = __esm({
     init_write();
     init_embind_adapter();
     init_extra_state_registry();
+    init_properties();
+    init_mp4_item_names();
   }
 });
 
@@ -2285,11 +2394,25 @@ var init_load_audio_data = __esm({
   }
 });
 
-// src/utils/tag-mapping.ts
-function parseNumeric(value) {
-  const parsed = Number.parseInt(value, 10);
+// src/utils/mirror-fields.ts
+function parseLeadingInt(raw) {
+  const parsed = Number.parseInt(raw, 10);
   return Number.isNaN(parsed) ? void 0 : parsed;
 }
+var MIRROR_FIELDS, DATE_MIRROR, TRACK_MIRROR;
+var init_mirror_fields = __esm({
+  "src/utils/mirror-fields.ts"() {
+    "use strict";
+    MIRROR_FIELDS = [
+      { raw: "date", numeric: "year" },
+      { raw: "trackNumber", numeric: "track" }
+    ];
+    DATE_MIRROR = MIRROR_FIELDS[0];
+    TRACK_MIRROR = MIRROR_FIELDS[1];
+  }
+});
+
+// src/utils/tag-mapping.ts
 function readExtendedTag(audioFile) {
   const tag = mapPropertiesToExtendedTag(audioFile.properties());
   const pictures = audioFile.getPictures();
@@ -2314,21 +2437,35 @@ function mapPropertiesToExtendedTag(props) {
     const values = props[propKey];
     if (!values || values.length === 0) continue;
     if (tagField === "year" || tagField === "track") {
-      const num = parseNumeric(values[0]);
+      const num = parseLeadingInt(values[0]);
       if (num !== void 0) tag[tagField] = num;
       if (propKey === "date") {
         tag.date = values.length === 1 ? values[0] : values;
       }
+      if (propKey === "trackNumber") {
+        tag.trackNumber = values.length === 1 ? values[0] : values;
+      }
     } else {
       tag[tagField] = values;
     }
   }
+  for (const [propKey, totalField] of [
+    ["trackNumber", "totalTracks"],
+    ["discNumber", "totalDiscs"]
+  ]) {
+    if (tag[totalField] !== void 0) continue;
+    const raw = props[propKey]?.[0];
+    const slash = raw?.indexOf("/") ?? -1;
+    if (raw === void 0 || slash === -1) continue;
+    const total = parseLeadingInt(raw.slice(slash + 1));
+    if (total !== void 0) tag[totalField] = total;
+  }
   for (const [key, values] of Object.entries(props)) {
     if (BASIC_PROPERTY_KEYS[key]) continue;
     if (!values || values.length === 0) continue;
     const camelKey = fromTagLibKey(key);
     if (NUMERIC_FIELDS.has(camelKey)) {
-      const num = parseNumeric(values[0]);
+      const num = parseLeadingInt(values[0]);
       if (num !== void 0) tag[camelKey] = num;
     } else if (camelKey === "compilation") {
       tag[camelKey] = values[0] === "1";
@@ -2341,8 +2478,29 @@ function mapPropertiesToExtendedTag(props) {
 function mergeTagUpdates(file, tags) {
   const currentProps = file.properties();
   const newProps = normalizeTagInput(tags);
+  reconcilePairFields(currentProps, newProps, tags);
   file.setProperties({ ...currentProps, ...newProps });
 }
+function reconcilePairFields(currentProps, newProps, input) {
+  const pairs = [
+    ["trackNumber", "totalTracks", "track"],
+    ["discNumber", "totalDiscs", "discNumber"]
+  ];
+  for (const [rawKey, totalKey, numericKey] of pairs) {
+    const incoming = newProps[rawKey]?.[0];
+    if (incoming?.includes("/")) {
+      newProps[totalKey] = [];
+      continue;
+    }
+    const numericOnly = input[numericKey] !== void 0 && input[rawKey] === void 0;
+    if (!numericOnly || incoming === void 0) continue;
+    const existing = currentProps[rawKey]?.[0];
+    const slash = existing?.indexOf("/") ?? -1;
+    if (existing !== void 0 && slash !== -1) {
+      newProps[rawKey] = [`${incoming}${existing.slice(slash)}`];
+    }
+  }
+}
 function normalizeTagInput(input) {
   const props = {};
   for (const field of [
@@ -2365,6 +2523,9 @@ function normalizeTagInput(input) {
   if (input.track !== void 0) {
     props.trackNumber = [String(input.track)];
   }
+  if (input.trackNumber !== void 0) {
+    props.trackNumber = Array.isArray(input.trackNumber) ? input.trackNumber : [input.trackNumber];
+  }
   for (const [field, val] of Object.entries(input)) {
     if (BASIC_FIELDS.has(field) || val === void 0) continue;
     if (field === "compilation") {
@@ -2377,6 +2538,12 @@ function normalizeTagInput(input) {
       props[field] = val;
     }
   }
+  for (const [rawField, totalField] of [
+    ["trackNumber", "totalTracks"],
+    ["discNumber", "totalDiscs"]
+  ]) {
+    if (props[rawField]?.[0]?.includes("/")) delete props[totalField];
+  }
   return props;
 }
 var BASIC_PROPERTY_KEYS, BASIC_FIELDS, NUMERIC_FIELDS;
@@ -2384,6 +2551,7 @@ var init_tag_mapping = __esm({
   "src/utils/tag-mapping.ts"() {
     "use strict";
     init_properties();
+    init_mirror_fields();
     BASIC_PROPERTY_KEYS = {
       title: "title",
       artist: "artist",
@@ -2401,7 +2569,8 @@ var init_tag_mapping = __esm({
       "genre",
       "year",
       "date",
-      "track"
+      "track",
+      "trackNumber"
     ]);
     NUMERIC_FIELDS = /* @__PURE__ */ new Set([
       "year",
@@ -2419,7 +2588,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "1.5.2";
+    VERSION = "1.6.0";
   }
 });
 
@@ -3101,8 +3270,9 @@ var Tags = {
   InvolvedPeople: "involvedPeople",
   Encoding: "encoding"
 };
+var VALID_TAG_NAMES = new Set(Object.values(Tags));
 function isValidTagName(name) {
-  return Object.values(Tags).includes(name);
+  return VALID_TAG_NAMES.has(name);
 }
 function getAllTagNames() {
   return Object.values(Tags);

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Main module exports for TagLib-Wasm
  *
- * TagLib v2.3 compiled to WebAssembly with TypeScript bindings
+ * TagLib v2.3.1 compiled to WebAssembly with TypeScript bindings
  * for universal audio metadata handling across all JavaScript runtimes.
  *
  * @module TagLib-Wasm