taglib-wasm
Version:
TagLib-Wasm is the universal tagging library for TypeScript/JavaScript platforms: Browsers, Node.js, Deno, Bun, Cloudflare Workers, and Electron apps
191 lines • 6.11 kB
TypeScript
/**
* Complex property definitions for structured metadata types.
* These are properties that contain multiple fields and cannot be
* represented as simple string values.
*
* These constants describe the shape of each complex property. Values are read
* and written through dedicated typed accessors, not a generic property call.
*
* @example
* ```typescript
* import type { Rating } from 'taglib-wasm';
*
* // Read via the typed accessor
* const ratings = file.getRatings();
* console.log(ratings[0].rating); // 0.0-1.0 normalized
*
* // Set a rating
* file.setRating(0.8, "user@example.com");
*
* // Or replace the full list
* file.setRatings([{ rating: 0.8, email: "user@example.com" }]);
* ```
*/
import type { Picture } from "../types.js";
import type { Chapter } from "../types/chapters.js";
/**
* Rating metadata representing track popularity/rating.
* Uses normalized 0.0-1.0 scale for cross-format compatibility.
*
* Format mappings:
* - ID3v2 (MP3): POPM frame (0-255 scale, normalized)
* - Vorbis (FLAC/OGG): RATING field
* - MP4: Freeform ----:com.apple.iTunes:RATING atom
*/
export interface Rating {
/** Normalized rating 0.0-1.0 (0 = unrated, 1.0 = highest) */
rating: number;
/** Email/ID identifying the rater (POPM standard) */
email?: string;
/** Play counter (if supported by format) */
counter?: number;
}
/**
* A raw ID3v2 frame (escape hatch for vendor and unsupported frames).
*
* `data` is the frame BODY only (no 10-byte header); the caller owns the
* body encoding. Reads of TagLib-modeled IDs (TIT2, APIC, ...) return
* TagLib's canonical rendering; see the raw-frames docs for caveats.
*/
export interface Id3v2Frame {
/** 4-character frame ID matching [A-Z0-9]{4}, e.g. "TXXX", "RGAD" */
id: string;
/** Frame body bytes (without the 10-byte frame header) */
data: Uint8Array;
/**
* Frame header flags. Reserved for forward compatibility: currently never
* populated — TagLib blanks frame header flags when rendering, so they
* cannot be observed or preserved. Read-only.
*/
flags?: number;
}
/**
* Unsynchronized lyrics text.
* For lyrics without timing information.
*/
export interface UnsyncedLyrics {
/** Full lyrics text */
text: string;
/** Description or content type */
description?: string;
/** ISO 639-2 language code (3 characters, e.g., "eng") */
language?: string;
}
/**
* Generic variant map for unknown/future complex properties.
* Used as escape hatch when type is not known at compile time.
*/
export type VariantMap = Record<string, unknown>;
/**
* Type map linking complex property keys to their value types.
*
* This is a descriptive type map, not the accessor surface — each complex
* property is reached through its own typed method:
*
* @example
* ```typescript
* const ratings = file.getRatings(); // Rating[]
* const pictures = file.getPictures(); // Picture[]
* const chapters = file.getChapters(); // Chapter[]
* ```
*
* Consumers can extend via module augmentation:
* ```typescript
* declare module "taglib-wasm" {
* interface ComplexPropertyValueMap {
* MY_CUSTOM: { foo: string };
* }
* }
* ```
*/
export interface ComplexPropertyValueMap {
/** Cover art and embedded images */
PICTURE: Picture;
/** Track/album rating (normalized 0.0-1.0) */
RATING: Rating;
/** Unsynchronized lyrics text */
LYRICS: UnsyncedLyrics;
/** Chapter markers (ID3v2 CHAP frames) */
CHAPTER: Chapter;
}
/**
* Union type of all valid complex property keys.
*/
export type ComplexPropertyKey = keyof ComplexPropertyValueMap;
/**
* Rich metadata object for complex properties.
* Contains descriptions, format support info, and underlying format mappings.
*
* Use this for introspection, documentation, or format-aware operations.
*/
export declare const COMPLEX_PROPERTIES: {
readonly PICTURE: {
readonly key: "PICTURE";
readonly description: "Embedded album art or images";
readonly type: "binary";
readonly supportedFormats: readonly ["ID3v2", "MP4", "Vorbis", "FLAC"];
readonly mappings: {
readonly id3v2: {
readonly frame: "APIC";
};
readonly mp4: "covr";
readonly vorbis: "METADATA_BLOCK_PICTURE";
readonly flac: "PICTURE";
};
};
readonly RATING: {
readonly key: "RATING";
readonly description: "Track rating (normalized 0.0-1.0)";
readonly type: "object";
readonly supportedFormats: readonly ["ID3v2", "Vorbis", "MP4"];
readonly mappings: {
readonly id3v2: {
readonly frame: "POPM";
};
readonly vorbis: "RATING";
readonly mp4: "----:com.apple.iTunes:RATING";
};
};
readonly LYRICS: {
readonly key: "LYRICS";
readonly description: "Unsynchronized lyrics text";
readonly type: "object";
readonly supportedFormats: readonly ["ID3v2", "Vorbis", "MP4"];
readonly mappings: {
readonly id3v2: {
readonly frame: "USLT";
};
readonly vorbis: "LYRICS";
readonly mp4: "©lyr";
};
};
readonly CHAPTER: {
readonly key: "CHAPTER";
readonly description: "Chapter markers with time ranges";
readonly type: "object";
readonly supportedFormats: readonly ["ID3v2"];
readonly mappings: {
readonly id3v2: {
readonly frame: "CHAP";
};
};
};
};
/**
* Type for the simple key map.
*/
export type ComplexPropertyKeyMap = {
readonly [K in ComplexPropertyKey]: K;
};
/**
* Simple string map for daily use.
* Avoids the `.key` ceremony when you just need the key string.
*
* @example
* ```typescript
* // Instead of: COMPLEX_PROPERTIES.RATING.key
* COMPLEX_PROPERTY_KEY.RATING; // "RATING"
* ```
*/
export declare const COMPLEX_PROPERTY_KEY: ComplexPropertyKeyMap;
//# sourceMappingURL=complex-properties.d.ts.map