taglib-wasm 0.3.1 → 0.3.2

package/README.md

@@ -1,25 +1,45 @@
 # taglib-wasm
 
-This is the Wasm version of [**TagLib**](https://taglib.org/), the most robust, de-facto standard for reading and editing metadata tags (Title, Album, Artist, etc.) in all popular audio formats. `taglib-wasm` exists because the JavaScipt/TypeScipt ecosystem had no battle-tested audio tagging library that supports reading and writing music metadata to all popular audio formats — until now!
-
-`taglib-wasm` stands on the shoulders of giants, including [TagLib](https://taglib.org/) itself, [Emscripten](https://emscripten.org/), and [Wasm](https://webassembly.org/) ([WebAssembly](https://webassembly.org/)).
-
-`taglib-wasm` aspires to be a universal solution for **JavaScript/TypeScript** platforms — Deno, Node.js, Bun, web browsers, and Cloudflare Workers. Note: This project is a baby, and you’re likely to experience some surprises at this stage of its development. I’m extremely motivated to help address them, since I’ll also be depending on this project.
+This is the Wasm version of [**TagLib**](https://taglib.org/), the most robust,
+de-facto standard for reading and editing metadata tags (Title, Album, Artist,
+etc.) in all popular audio formats. `taglib-wasm` exists because the
+JavaScipt/TypeScipt ecosystem had no battle-tested audio tagging library that
+supports reading and writing music metadata to all popular audio formats — until
+now!
+
+`taglib-wasm` stands on the shoulders of giants, including
+[TagLib](https://taglib.org/) itself, [Emscripten](https://emscripten.org/), and
+[Wasm](https://webassembly.org/) ([WebAssembly](https://webassembly.org/)).
+
+`taglib-wasm` aspires to be a universal solution for **JavaScript/TypeScript**
+platforms — Deno, Node.js, Bun, web browsers, and Cloudflare Workers. Note: This
+project is a baby, and you’re likely to experience some surprises at this stage
+of its development. I’m extremely motivated to help address them, since I’ll
+also be depending on this project.
 
 ## 🤔 Why?
 
-Because there’s nothing like it. [`mp3tag.js`](https://mp3tag.js.org/) is mature and active, but only supports MP3 files and ID3 tags. TagLib was an ideal choice from a maturity and capabilities point of view, but wrappers like `node-taglib` appeared to be dormant, and I wanted to avoid making users install platform-specific dependencies whenever possible.
+Because there’s nothing like it. [`mp3tag.js`](https://mp3tag.js.org/) is mature
+and active, but only supports MP3 files and ID3 tags. TagLib was an ideal choice
+from a maturity and capabilities point of view, but wrappers like `node-taglib`
+appeared to be dormant, and I wanted to avoid making users install
+platform-specific dependencies whenever possible.
 
 ## 🎯 Features
 
-- **✅ Universal compatibility** – Works with Deno, Node.js, Bun, web browsers, and Cloudflare Workers
+- **✅ Universal compatibility** – Works with Deno, Node.js, Bun, web browsers,
+  and Cloudflare Workers
 - **✅ TypeScript first** – Complete type definitions and modern API
-- **✅ Full audio format support** – Supports all audio formats supported by TagLib
-- **✅ Format abstraction** – `taglib-wasm` deals with how tags are read from/written to in different file formats
+- **✅ Full audio format support** – Supports all audio formats supported by
+  TagLib
+- **✅ Format abstraction** – `taglib-wasm` deals with how tags are read
+  from/written to in different file formats
 - **✅ Zero dependencies** – Self-contained WASM bundle
 - **✅ Memory efficient** – In-memory processing without filesystem access
-- **✅ Production ready** – Growing test suite helps ensure safety and reliability
-- **🆕 Two API styles** – Choose between Simple (3 functions) or Core (full control) APIs
+- **✅ Production ready** – Growing test suite helps ensure safety and
+  reliability
+- **🆕 Two API styles** – Choose between Simple (3 functions) or Core (full
+  control) APIs
 
 ## 📦 Installation
 
@@ -35,7 +55,19 @@ import { TagLib } from "npm:taglib-wasm";
 npm install taglib-wasm
 ```
 
-**Note:** The NPM package ships TypeScript source files. Use a TypeScript loader like [`tsx`](https://github.com/privatenumber/tsx):
+The package uses TypeScript. You have two options:
+
+#### Option 1: Use Node’s native TypeScript support
+
+```bash
+# Node.js 22.6.0+ with experimental flag
+node --experimental-strip-types your-script.ts
+
+# Node.js 23.6.0+ (no flag needed)
+node your-script.ts
+```
+
+#### Option 2: TypeScript loader (recommended for production)
 
 ```bash
 npm install --save-dev tsx
@@ -52,16 +84,17 @@ bun add taglib-wasm
 
 ### Simple API
 
-Inspired by [go-taglib](https://github.com/sentriz/go-taglib)’s excellent developer experience:
+This was inspired by [go-taglib](https://github.com/sentriz/go-taglib), a
+similar project for Go created at about the same time.
 
 ```typescript
 import { readProperties, readTags, writeTags } from "taglib-wasm/simple";
 
-// Read tags - just one function call!
+// Read tags
 const tags = await readTags("song.mp3");
 console.log(tags.title, tags.artist, tags.album);
 
-// Write tags - simple as can be
+// Write tags
 await writeTags("song.mp3", {
   title: "New Title",
   artist: "New Artist",
@@ -75,7 +108,7 @@ console.log(`Duration: ${props.length}s, Bitrate: ${props.bitrate} kbps`);
 
 ### Core API
 
-Full control when you need it:
+The Core API provides full control for more advanced applications.
 
 ```typescript
 import { TagLib } from "taglib-wasm";
@@ -111,19 +144,50 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
+### Tag Constants
+
+taglib-wasm provides type-safe tag constants with IDE autocomplete:
+
+```typescript
+import { Tags } from "taglib-wasm";
+
+// Use constants for better type safety and autocomplete
+const properties = file.properties();
+
+// Read properties
+const title = properties[Tags.Title]?.[0];
+const albumArtist = properties[Tags.AlbumArtist]?.[0];
+const musicBrainzId = properties[Tags.MusicBrainzArtistId]?.[0];
+
+// Write properties
+file.setProperties({
+  [Tags.Title]: ["My Song"],
+  [Tags.AlbumArtist]: ["Various Artists"],
+  [Tags.Bpm]: ["128"]
+});
+
+// All constants provide IDE autocomplete
+Tags.Title         // → "TITLE"
+Tags.Artist        // → "ARTIST"
+Tags.AlbumArtist   // → "ALBUMARTIST"
+Tags.TrackGain     // → "REPLAYGAIN_TRACK_GAIN"
+// ... and many more
+```
+
+See [Tag Name Constants](docs/Tag-Name-Constants.md) for the complete list of available tags and format-specific mappings.
+
 ## Platform examples
 
-### Node.js
+### Deno
 
 ```typescript
-import { TagLib } from "taglib-wasm";
-import { readFile } from "fs/promises";
+import { TagLib } from "npm:taglib-wasm";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
 // Load audio file from filesystem
-const audioData = await readFile("song.mp3");
+const audioData = await Deno.readFile("song.mp3");
 const file = taglib.openFile(audioData);
 
 // Read metadata
@@ -150,17 +214,18 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
-### Bun
+### Node.js
 
 ```typescript
 import { TagLib } from "taglib-wasm";
+import { readFile } from "fs/promises";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
-// Load from file system (Bun's native file API)
-const audioData = await Bun.file("song.mp3").arrayBuffer();
-const file = taglib.openFile(new Uint8Array(audioData));
+// Load audio file from filesystem
+const audioData = await readFile("song.mp3");
+const file = taglib.openFile(audioData);
 
 // Read metadata
 const tags = file.tag();
@@ -186,7 +251,7 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
-### Browser
+### Bun
 
 ```typescript
 import { TagLib } from "taglib-wasm";
@@ -194,11 +259,9 @@ import { TagLib } from "taglib-wasm";
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
-// Load from file input or fetch
-const fileInput = document.querySelector('input[type="file"]');
-const audioFile = fileInput.files[0];
-const audioData = new Uint8Array(await audioFile.arrayBuffer());
-const file = taglib.openFile(audioData);
+// Load from file system (Bun's native file API)
+const audioData = await Bun.file("song.mp3").arrayBuffer();
+const file = taglib.openFile(new Uint8Array(audioData));
 
 // Read metadata
 const tags = file.tag();
@@ -224,16 +287,18 @@ console.log("Updated tags:", file.tag());
 file.dispose();
 ```
 
-### Deno
+### Browser
 
 ```typescript
-import { TagLib } from "npm:taglib-wasm";
+import { TagLib } from "taglib-wasm";
 
 // Initialize taglib-wasm
 const taglib = await TagLib.initialize();
 
-// Load audio file from filesystem
-const audioData = await Deno.readFile("song.mp3");
+// Load from file input or fetch
+const fileInput = document.querySelector('input[type="file"]');
+const audioFile = fileInput.files[0];
+const audioData = new Uint8Array(await audioFile.arrayBuffer());
 const file = taglib.openFile(audioData);
 
 // Read metadata
@@ -269,7 +334,8 @@ export default {
   async fetch(request: Request): Promise<Response> {
     if (request.method === "POST") {
       try {
-        // Initialize taglib-wasm
+        // Initialize taglib-wasm with Workers-specific configuration
+        // See docs/Cloudflare-Workers.md for memory configuration details
         const taglib = await TagLib.initialize({
           memory: { initial: 8 * 1024 * 1024 }, // 8MB for Workers
         });
@@ -319,22 +385,30 @@ export default {
 
 `tag-wasm` is designed to support all formats supported by TagLib:
 
-- ✅ **.m4a (.mp4)** – Standard MPEG-4/AAC metadata for AAC and Apple Lossless audio
+- ✅ **.m4a (.mp4)** – Standard MPEG-4/AAC metadata for AAC and Apple Lossless
+  audio
 - ✅ **.mp3** – ID3v2 and ID3v1 tags
 - ✅ **.flac** – Vorbis comments and audio properties
 - ✅ **.wav** – INFO chunk metadata
-- ✅ **Legacy formats**: Opus, APE, MPC, WavPack, TrueAudio, and more
+- ✅ **Legacy formats** – Opus, APE, MPC, WavPack, TrueAudio, and more
 
 ## 🎯 Extended Metadata with PropertyMap
 
-`taglib-wasm` provides a **PropertyMap API** for accessing extended metadata beyond the basic tags. This allows you to read and write format-specific fields and custom metadata.
+`taglib-wasm` provides a **PropertyMap API** for accessing extended metadata
+beyond the basic tags. This allows you to read and write format-specific fields
+and custom metadata.
 
 ### AcoustID example
 
 ```typescript
-// Using PropertyMap API to set extended metadata
+import { Tags } from "taglib-wasm";
+
+// Using PropertyMap API to set extended metadata with tag constants
+file.setProperty(Tags.AcoustidFingerprint, "AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
+file.setProperty(Tags.AcoustidId, "e7359e88-f1f7-41ed-b9f6-16e58e906997");
+
+// Or using string property names
 file.setProperty("ACOUSTID_FINGERPRINT", "AQADtMmybfGO8NCNEESLnzHyXNOHeHnG...");
-file.setProperty("ACOUSTID_ID", "e7359e88-f1f7-41ed-b9f6-16e58e906997");
 
 // Note: Property keys may vary by format
 // Use file.properties() to see all available properties
@@ -344,20 +418,23 @@ file.save(); // Don't forget to save!
 ### MusicBrainz example
 
 ```typescript
-// MusicBrainz metadata using PropertyMap
-file.setProperty("MUSICBRAINZ_TRACKID", "f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
-file.setProperty("MUSICBRAINZ_ALBUMID", "a1b2c3d4-e5f6-7890-abcd-ef1234567890");
-file.setProperty("MUSICBRAINZ_ARTISTID", "12345678-90ab-cdef-1234-567890abcdef");
+// MusicBrainz metadata using PropertyMap with tag constants
+file.setProperty(Tags.MusicBrainzTrackId, "f4d1b6b8-8c1e-4d9a-9f2a-1234567890ab");
+file.setProperty(Tags.MusicBrainzAlbumId, "a1b2c3d4-e5f6-7890-abcd-ef1234567890");
+file.setProperty(
+  Tags.MusicBrainzArtistId,
+  "12345678-90ab-cdef-1234-567890abcdef",
+);
 ```
 
 ### Volume example
 
 ```typescript
-// ReplayGain volume normalization
-file.setProperty("REPLAYGAIN_TRACK_GAIN", "-6.54 dB");
-file.setProperty("REPLAYGAIN_TRACK_PEAK", "0.987654");
-file.setProperty("REPLAYGAIN_ALBUM_GAIN", "-8.12 dB");
-file.setProperty("REPLAYGAIN_ALBUM_PEAK", "0.995432");
+// ReplayGain volume normalization with tag constants
+file.setProperty(Tags.TrackGain, "-6.54 dB");
+file.setProperty(Tags.TrackPeak, "0.987654");
+file.setProperty(Tags.AlbumGain, "-8.12 dB");
+file.setProperty(Tags.AlbumPeak, "0.995432");
 ```
 
 ### Extended fields
@@ -366,20 +443,20 @@ file.setProperty("REPLAYGAIN_ALBUM_PEAK", "0.995432");
 // Using PropertyMap to set multiple properties at once
 const properties = file.properties(); // Get current properties
 
-// Set extended metadata
+// Set extended metadata with tag constants
 file.setProperties({
-  ALBUMARTIST: ["Various Artists"],
-  COMPOSER: ["Composer Name"],
-  BPM: ["120"],
-  COMPILATION: ["1"],
-  DISCNUMBER: ["1"],
-  TRACKTOTAL: ["12"],
+  [Tags.AlbumArtist]: ["Various Artists"],
+  [Tags.Composer]: ["Composer Name"],
+  [Tags.Bpm]: ["120"],
+  [Tags.Compilation]: ["1"],
+  [Tags.DiscNumber]: ["1"],
+  [Tags.TrackTotal]: ["12"],
   // Note: Property keys vary by format
 });
 
 // Or set individual properties
-file.setProperty("ALBUMARTIST", "Various Artists");
-file.setProperty("COMPOSER", "Composer Name");
+file.setProperty(Tags.AlbumArtist, "Various Artists");
+file.setProperty(Tags.Composer, "Composer Name");
 ```
 
 ## 🏗️ Development
@@ -442,23 +519,29 @@ npm test
 # ✅ MP3  - ID3v1/v2 tag support
 # ✅ FLAC - Vorbis comments and properties
 # ✅ OGG  - Vorbis comments
-# ✅ M4A  - iTunes-compatible metadata atoms
+# ✅ M4A  - MPEG-4 (AAC and Apple Lossless) metadata
 ```
 
 ## 🔧 Technical Implementation
 
 ### Key architecture decisions
 
-1. **Memory Management**: Uses Emscripten's `allocate()` for reliable JS↔WASM data transfer
-2. **Buffer-Based Processing**: `TagLib::ByteVectorStream` enables in-memory file processing
+1. **Memory Management**: Uses Emscripten's `allocate()` for reliable JS↔WASM
+   data transfer
+2. **Buffer-Based Processing**: `TagLib::ByteVectorStream` enables in-memory
+   file processing
 3. **C++ Wrapper**: Custom C functions bridge TagLib's C++ API to WASM exports
-4. **Type Safety**: Complete TypeScript definitions for all audio formats and metadata
+4. **Type Safety**: Complete TypeScript definitions for all audio formats and
+   metadata
 
 ### Critical implementation details
 
-- **ByteVectorStream**: Enables processing audio files from memory buffers without filesystem
-- **ID-based Object Management**: C++ objects managed via integer IDs for memory safety
-- **Emscripten allocate()**: Ensures proper memory synchronization between JS and WASM
+- **ByteVectorStream**: Enables processing audio files from memory buffers
+  without filesystem
+- **ID-based Object Management**: C++ objects managed via integer IDs for memory
+  safety
+- **Emscripten allocate()**: Ensures proper memory synchronization between JS
+  and WASM
 - **UTF-8 String Handling**: Proper encoding for international metadata
 
 ## 📚 API Reference
@@ -536,51 +619,44 @@ interface Tag {
 type PropertyMap = { [key: string]: string[] };
 ```
 
-## 🎛️ Configuration
+## 📖 Additional Documentation
 
-```typescript
-interface TagLibConfig {
-  memory?: {
-    initial?: number; // Initial memory size (default: 16MB)
-    maximum?: number; // Maximum memory size (default: 256MB)
-  };
-  debug?: boolean; // Enable debug output
-}
-```
+- [**Tag Name Constants**](docs/Tag-Name-Constants.md) - Comprehensive reference for standard tag names and cross-format mapping
+- [**Automatic Tag Mapping**](docs/Automatic-Tag-Mapping.md) - How taglib-wasm handles format-specific tag differences
+- [**Implementation Details**](docs/Implementation.md) - Technical details about the Wasm implementation
+- [**Runtime Compatibility**](docs/Runtime-Compatibility.md) - Platform-specific setup and considerations
 
 ## 🌐 Runtime Compatibility
 
-`taglib-wasm` works seamlessly across all major JavaScript runtimes:
+`taglib-wasm` works across all major JavaScript runtimes:
 
-| Runtime     | Status  | Installation                      | Performance | TypeScript |
-| ----------- | ------- | --------------------------------- | ----------- | ---------- |
-| **Deno**    | ✅ Full | `npm:taglib-wasm` | Excellent   | Native     |
-| **Bun**     | ✅ Full | `bun add taglib-wasm`             | Excellent   | Native     |
-| **Node.js** | ✅ Full | `npm install taglib-wasm`         | Good        | Via loader |
-| **Browser** | ✅ Full | CDN/bundler                       | Good        | Via build  |
+| Runtime     | Status  | Installation              | Performance | TypeScript |
+| ----------- | ------- | ------------------------- | ----------- | ---------- |
+| **Deno**    | ✅ Full | `npm:taglib-wasm`         | Excellent   | Native     |
+| **Bun**     | ✅ Full | `bun add taglib-wasm`     | Excellent   | Native     |
+| **Node.js** | ✅ Full | `npm install taglib-wasm` | Good        | Native/tsx |
+| **Browser** | ✅ Full | CDN/bundler               | Good        | Via build  |
 
-**📖 See [docs/Runtime-Compatibility.md](docs/Runtime-Compatibility.md) for detailed runtime information**
+**📖 See [docs/Runtime-Compatibility.md](docs/Runtime-Compatibility.md) for
+detailed runtime information**
 
 ## 🚧 Known Limitations
 
-- **File Writing**: Saves only affect in-memory representation (no filesystem persistence)
-- **Large Files**: Memory usage scales with file size (entire file loaded into memory)
-- **Concurrent Access**: Not thread-safe (JavaScript single-threaded nature)
+- **File Writing** – Saves only affect in-memory representation (no filesystem
+  persistence)
+- **Large Files** – Memory usage scales with file size (entire file loaded into
+  memory)
+- **Concurrent Access** – Not thread-safe (JavaScript single-threaded nature)
 
 ## 🤝 Contributing
 
-Contributions welcome! Areas of interest:
-
-- Additional format support (DSF, DSDIFF, etc.)
-- Advanced metadata implementation (PropertyMap integration)
-- Performance optimizations
-- Runtime-specific optimizations
-- Documentation improvements
+Contributions welcome!
 
 ## 📄 License
 
 - **This project**: MIT License (see [LICENSE](LICENSE))
-- **TagLib library**: LGPL/MPL dual license (see [lib/taglib/COPYING.LGPL](lib/taglib/COPYING.LGPL))
+- **TagLib library**: LGPL/MPL dual license (see
+  [lib/taglib/COPYING.LGPL](lib/taglib/COPYING.LGPL))
 
 ## 🙏 Acknowledgments
 

package/index.ts

@@ -7,6 +7,7 @@
 
 export { AudioFileImpl as AudioFile, TagLib, createTagLib } from "./src/taglib.ts";
 export { readTags, writeTags, readProperties } from "./src/simple.ts";
+export { Tags, FormatMappings, isValidTagName, getAllTagNames } from "./src/constants.ts";
 export type {
   AudioFormat,
   AudioProperties,
@@ -18,6 +19,7 @@ export type {
   PropertyMap,
   Tag,
   TagLibConfig,
+  TagName,
 } from "./src/types.ts";
 export type { TagLibModule, WasmModule } from "./src/wasm.ts";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taglib-wasm",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "TagLib compiled to WebAssembly with TypeScript bindings for universal audio metadata handling",
   "main": "index.ts",
   "types": "index.ts",
@@ -32,6 +32,9 @@
     "publish:npm": "echo 'Use GitHub Actions workflow for publishing'",
     "publish:github": "echo 'Use GitHub Actions workflow for publishing'"
   },
+  "engines": {
+    "node": ">=22.6.0"
+  },
   "keywords": [
     "taglib",
     "webassembly",

package/src/constants.ts

@@ -0,0 +1,227 @@
+/**
+ * Standard tag property names used by TagLib.
+ * These constants provide type-safe access to tag properties with IDE autocomplete.
+ * 
+ * @example
+ * ```typescript
+ * import { Tags } from 'taglib-wasm';
+ * 
+ * // Read tags
+ * const title = file.tag.properties.get(Tags.Title);
+ * const artist = file.tag.properties.get(Tags.Artist);
+ * 
+ * // Write tags
+ * file.tag.properties.set(Tags.Album, "Dark Side of the Moon");
+ * file.tag.properties.set(Tags.Year, "1973");
+ * ```
+ */
+export const Tags = {
+  // Basic Properties
+  /** Track/song title */
+  Title: 'TITLE',
+  /** Primary performer(s) */
+  Artist: 'ARTIST',
+  /** Album/collection name */
+  Album: 'ALBUM',
+  /** Date of recording (year) */
+  Date: 'DATE',
+  /** Track number on album */
+  TrackNumber: 'TRACKNUMBER',
+  /** Musical genre */
+  Genre: 'GENRE',
+  /** Comments/notes */
+  Comment: 'COMMENT',
+  
+  // Extended Properties
+  /** Band/orchestra/ensemble */
+  AlbumArtist: 'ALBUMARTIST',
+  /** Original composer(s) */
+  Composer: 'COMPOSER',
+  /** Copyright information */
+  Copyright: 'COPYRIGHT',
+  /** Encoding software/person */
+  EncodedBy: 'ENCODEDBY',
+  /** Disc number for multi-disc sets */
+  DiscNumber: 'DISCNUMBER',
+  /** Beats per minute */
+  Bpm: 'BPM',
+  /** Lyrics/text writer(s) */
+  Lyricist: 'LYRICIST',
+  /** Conductor */
+  Conductor: 'CONDUCTOR',
+  /** Person who remixed */
+  Remixer: 'REMIXEDBY',
+  /** Language of vocals/lyrics */
+  Language: 'LANGUAGE',
+  /** Publisher */
+  Publisher: 'PUBLISHER',
+  /** Mood/atmosphere */
+  Mood: 'MOOD',
+  /** Media type (CD, vinyl, etc.) */
+  Media: 'MEDIA',
+  /** Radio station owner */
+  RadioStationOwner: 'RADIOSTATIONOWNER',
+  /** Producer */
+  Producer: 'PRODUCER',
+  /** Album subtitle */
+  Subtitle: 'SUBTITLE',
+  /** Release label */
+  Label: 'LABEL',
+  
+  // Sorting Properties
+  /** Sort name for title */
+  TitleSort: 'TITLESORT',
+  /** Sort name for artist */
+  ArtistSort: 'ARTISTSORT',
+  /** Sort name for album artist */
+  AlbumArtistSort: 'ALBUMARTISTSORT',
+  /** Sort name for album */
+  AlbumSort: 'ALBUMSORT',
+  /** Sort name for composer */
+  ComposerSort: 'COMPOSERSORT',
+  
+  // Identifiers
+  /** International Standard Recording Code */
+  Isrc: 'ISRC',
+  /** Amazon Standard Identification Number */
+  Asin: 'ASIN',
+  /** Catalog number */
+  CatalogNumber: 'CATALOGNUMBER',
+  /** Barcode (EAN/UPC) */
+  Barcode: 'BARCODE',
+  
+  // MusicBrainz Identifiers
+  /** MusicBrainz Artist ID */
+  MusicBrainzArtistId: 'MUSICBRAINZ_ARTISTID',
+  /** MusicBrainz Release Artist ID */
+  MusicBrainzReleaseArtistId: 'MUSICBRAINZ_ALBUMARTISTID',
+  /** MusicBrainz Work ID */
+  MusicBrainzWorkId: 'MUSICBRAINZ_WORKID',
+  /** MusicBrainz Release ID */
+  MusicBrainzReleaseId: 'MUSICBRAINZ_ALBUMID',
+  /** MusicBrainz Recording ID */
+  MusicBrainzRecordingId: 'MUSICBRAINZ_TRACKID',
+  /** MusicBrainz Track ID (deprecated, use RecordingId) */
+  MusicBrainzTrackId: 'MUSICBRAINZ_TRACKID',
+  /** MusicBrainz Release Group ID */
+  MusicBrainzReleaseGroupId: 'MUSICBRAINZ_RELEASEGROUPID',
+  /** MusicBrainz Release Track ID */
+  MusicBrainzReleaseTrackId: 'MUSICBRAINZ_RELEASETRACKID',
+  
+  // Podcast Properties
+  /** Podcast identifier */
+  PodcastId: 'PODCASTID',
+  /** Podcast URL */
+  PodcastUrl: 'PODCASTURL',
+  
+  // Grouping and Work
+  /** Content group/work */
+  Grouping: 'GROUPING',
+  /** Work name */
+  Work: 'WORK',
+  
+  // Additional Metadata
+  /** Lyrics content */
+  Lyrics: 'LYRICS',
+  /** Album gain (ReplayGain) */
+  AlbumGain: 'REPLAYGAIN_ALBUM_GAIN',
+  /** Album peak (ReplayGain) */
+  AlbumPeak: 'REPLAYGAIN_ALBUM_PEAK',
+  /** Track gain (ReplayGain) */
+  TrackGain: 'REPLAYGAIN_TRACK_GAIN',
+  /** Track peak (ReplayGain) */
+  TrackPeak: 'REPLAYGAIN_TRACK_PEAK',
+  
+  // Special handling
+  /** Original artist for covers */
+  OriginalArtist: 'ORIGINALARTIST',
+  /** Original album */
+  OriginalAlbum: 'ORIGINALALBUM',
+  /** Original release date */
+  OriginalDate: 'ORIGINALDATE',
+  /** Script/writing system */
+  Script: 'SCRIPT',
+  /** Involved people list */
+  InvolvedPeopleList: 'INVOLVEDPEOPLELIST',
+  
+  // Technical Properties
+  /** Encoder settings/software */
+  EncoderSettings: 'ENCODERSETTINGS',
+  /** Source media */
+  SourceMedia: 'SOURCEMEDIA',
+} as const;
+
+/**
+ * Type representing all valid tag property names
+ */
+export type TagName = typeof Tags[keyof typeof Tags];
+
+/**
+ * Type guard to check if a string is a valid tag name
+ */
+export function isValidTagName(name: string): name is TagName {
+  return Object.values(Tags).includes(name as TagName);
+}
+
+/**
+ * Get all available tag names as an array
+ */
+export function getAllTagNames(): readonly TagName[] {
+  return Object.values(Tags);
+}
+
+/**
+ * Format-specific tag mappings (for reference only - TagLib handles these automatically)
+ * This shows how standard property names map to format-specific identifiers.
+ */
+export const FormatMappings = {
+  Title: {
+    id3v2: 'TIT2',
+    mp4: '©nam',
+    vorbis: 'TITLE',
+    ape: 'Title',
+    riff: 'INAM'
+  },
+  Artist: {
+    id3v2: 'TPE1',
+    mp4: '©ART',
+    vorbis: 'ARTIST',
+    ape: 'Artist',
+    riff: 'IART'
+  },
+  Album: {
+    id3v2: 'TALB',
+    mp4: '©alb',
+    vorbis: 'ALBUM',
+    ape: 'Album',
+    riff: 'IPRD'
+  },
+  Date: {
+    id3v2: 'TDRC',
+    mp4: '©day',
+    vorbis: 'DATE',
+    ape: 'Year',
+    riff: 'ICRD'
+  },
+  Genre: {
+    id3v2: 'TCON',
+    mp4: '©gen',
+    vorbis: 'GENRE',
+    ape: 'Genre',
+    riff: 'IGNR'
+  },
+  Comment: {
+    id3v2: 'COMM',
+    mp4: '©cmt',
+    vorbis: 'COMMENT',
+    ape: 'Comment',
+    riff: 'ICMT'
+  },
+  TrackNumber: {
+    id3v2: 'TRCK',
+    mp4: 'trkn',
+    vorbis: 'TRACKNUMBER',
+    ape: 'Track',
+    riff: 'ITRK'
+  }
+} as const;

package/src/types.ts

@@ -303,6 +303,11 @@ export interface PropertyMap {
   [key: string]: string[];
 }
 
+/**
+ * Re-export TagName type from constants
+ */
+export type { TagName } from "./constants.ts";
+
 /**
  * Picture/artwork data
  */