tiny-essentials 1.28.0 → 1.28.2

package/dist/v1/basics/mediaContent.d.mts

@@ -1,130 +1,10 @@
 /**
+ * A type representing either a static string or a function that returns a string, used to resolve an unknown artist's name.
  * @typedef {string|(() => string)} UnknownArtistGetter
  */
-/**
- * Represents an image attachment template.
- * @template {Uint8Array|string} PictureData
- * @typedef {Object} IPictureTemplate
- * @property {string} format - The MIME type of the image (e.g., 'image/jpeg').
- * @property {PictureData} data - The raw binary data of the image.
- * @property {string} [description] - An optional textual description of the image.
- * @property {string} [type] - The specific type of picture (e.g., 'cover', 'front', 'back').
- * @property {string} [name] - The filename associated with the image.
- */
-/**
- * Represents an image attachment, such as album art.
- * @typedef {IPictureTemplate<string>} IPicture
- */
-/**
- * A numeric structure representing track or disk indexing.
- * @typedef {{no: number|null, of: number|null}} MediaNumber
- */
-/**
- * This metadata structure is modeled template.
- *
- * @template {IPictureTemplate<Uint8Array|string>} IPictureContent
- * @typedef {Object} ContentMetadataTemplate
- * @property {string|null} title - The title of the track.
- * @property {string|null} album - The name of the album.
- * @property {string|null} albumartist - The primary artist of the album.
- * @property {string[]} albumartists - An array of artists associated with the album.
- * @property {string[]} genre - An array of genres associated with the track.
- * @property {string[]} label - The record label.
- * @property {string[]} composer - The composer of the track.
- * @property {number|null} year - The release year.
- * @property {string|null} artist - The primary artist of the track.
- * @property {string[]} artists - An array of artists associated with the track.
- * @property {MediaNumber} disk - Disk information containing the current disk number and total disks.
- * @property {MediaNumber} track - Track information containing the current track number and total tracks.
- * @property {IPictureContent[]} [picture] - An array of picture objects containing album art.
- */
-/**
- * This metadata structure is modeled after the standard output of the
- * `music-metadata@11.13.0` npm package.
- *
- * @typedef {ContentMetadataTemplate<IPicture>} MediaContentMetadata
- */
-/**
- * The core properties required for any content item within the media system.
- * @typedef {Object} MediaContentBase
- * @property {string} id - Unique identifier.
- * @property {string} title - Name of the track/message.
- * @property {string} artist - Artist or speaker name.
- * @property {number} duration - Duration in milliseconds.
- * @property {string} url - Source URL/Path.
- * @property {number} [weight=1] - Probability multiplier for random selection mode.
- */
-/**
- * The final content object used within the media, combining
- * core playback properties with rich metadata.
- *
- * @typedef {MediaContentBase & MediaContentMetadata} MediaContent
- */
-/**
- * A promise that resolves to an object containing the extracted metadata.
- * @callback ParseMediaContentMetadata
- * @param {Blob} data - The raw file blob.
- * @returns {Promise<{ common: Partial<ContentMetadataTemplate<IPictureTemplate<Uint8Array|string>>> }>} A promise resolving to the common metadata properties.
- */
-/**
- * @typedef {Object} LoadingMediaProgress
- * @property {'loading'|'success'} status - The current status of the operation.
- * @property {LoadingProgressStage} stage - The current execution stage.
- * @property {ProgressEvent<EventTarget>} [event] - The current loading event.
- * @property {string} url - The URL being processed.
- */
-/**
- * @typedef {'INITIALIZING'|'DOWNLOADING'|'METADATA_LOADED'|'EXTRACTING_ID3'|'COMPLETE'} LoadingProgressStage
- */
-/**
- * @typedef {'INITIALIZING'|'DOWNLOADING'|'METADATA'|'ID3'|'UNKNOWN'} LoadingErrorStage
- */
-/**
- * @typedef {Object} MediaLoadingErrorData
- * @property {Error} error - The original error object.
- * @property {string} url - The URL that failed.
- * @property {LoadingErrorStage} stage - The stage where it failed.
- */
-/** @type {Map<string, number>} */
-export const _blobCounter: Map<string, number>;
-export function getMediaContentBase(): MediaContentBase;
-export function getMediaContentMetadata(): MediaContentMetadata;
-/**
- * Custom error class to provide detailed context during the content preparation process.
- * @extends Error
- */
-export class MediaLoadingError extends Error {
-    /**
-     * @param {string} message - Human-readable error message.
-     * @param {string} url - The URL that caused the error.
-     * @param {LoadingErrorStage} stage - The stage where the error occurred.
-     */
-    constructor(message: string, url: string, stage: LoadingErrorStage);
-    url: string;
-    stage: LoadingErrorStage;
-}
-export function generateSimpleHash(str: string): Promise<string>;
-export function convertToBlobUrl(data: Uint8Array | string, format?: string): string;
-export function blobUrlToBase64(url: string): Promise<string>;
-export function revokeContentUrls(content: MediaContent): void;
-export function valMediaContentMetadata(common: ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>): void;
-export function valMediaContentMetadataPartial(common: Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>): void;
-export function extractMediaId3Tags(url: string, parseFile: ParseMediaContentMetadata): Promise<MediaContentMetadata>;
-export function parseMediaMetadata(source: string | HTMLMediaElement, defaultMetadata?: Partial<MediaContentBase & MediaContentMetadata> & {
-    id?: string;
-    weight?: number;
-}, metadata?: Partial<MediaContentBase & MediaContentMetadata> & {
-    id?: string;
-    weight?: number;
-}, parseFile?: ParseMediaContentMetadata, callbacks?: {
-    onProgress?: ((progress: LoadingMediaProgress) => void) | undefined;
-    onError?: ((error: MediaLoadingErrorData) => void) | undefined;
-}, unknownArtist?: UnknownArtistGetter): Promise<MediaContent>;
 export type UnknownArtistGetter = string | (() => string);
-/**
- * Represents an image attachment template.
- */
-export type IPictureTemplate<PictureData extends Uint8Array | string> = {
+export type PictureDataType = Uint8Array | string;
+export type IPictureTemplate<PictureData extends PictureDataType> = {
     /**
      * - The MIME type of the image (e.g., 'image/jpeg').
      */
@@ -136,31 +16,22 @@ export type IPictureTemplate<PictureData extends Uint8Array | string> = {
     /**
      * - An optional textual description of the image.
      */
-    description?: string | undefined;
+    description?: string;
     /**
      * - The specific type of picture (e.g., 'cover', 'front', 'back').
      */
-    type?: string | undefined;
+    type?: string;
     /**
      * - The filename associated with the image.
      */
-    name?: string | undefined;
+    name?: string;
 };
-/**
- * Represents an image attachment, such as album art.
- */
 export type IPicture = IPictureTemplate<string>;
-/**
- * A numeric structure representing track or disk indexing.
- */
 export type MediaNumber = {
     no: number | null;
     of: number | null;
 };
-/**
- * This metadata structure is modeled template.
- */
-export type ContentMetadataTemplate<IPictureContent extends IPictureTemplate<Uint8Array | string>> = {
+export type ContentMetadataTemplate<IPictureContent extends IPictureTemplate<PictureDataType>> = {
     /**
      * - The title of the track.
      */
@@ -212,16 +83,9 @@ export type ContentMetadataTemplate<IPictureContent extends IPictureTemplate<Uin
     /**
      * - An array of picture objects containing album art.
      */
-    picture?: IPictureContent[] | undefined;
+    picture?: IPictureContent[];
 };
-/**
- * This metadata structure is modeled after the standard output of the
- * `music-metadata@11.13.0` npm package.
- */
-export type MediaContentMetadata = ContentMetadataTemplate<IPicture>;
-/**
- * The core properties required for any content item within the media system.
- */
+export type MediaContentMetadata<PictureData extends PictureDataType> = ContentMetadataTemplate<IPictureTemplate<PictureData>>;
 export type MediaContentBase = {
     /**
      * - Unique identifier.
@@ -246,24 +110,17 @@ export type MediaContentBase = {
     /**
      * - Probability multiplier for random selection mode.
      */
-    weight?: number | undefined;
+    weight?: number;
 };
-/**
- * The final content object used within the media, combining
- * core playback properties with rich metadata.
- */
-export type MediaContent = MediaContentBase & MediaContentMetadata;
-/**
- * A promise that resolves to an object containing the extracted metadata.
- */
+export type MediaContent<PictureData extends PictureDataType> = MediaContentBase & MediaContentMetadata<PictureData>;
 export type ParseMediaContentMetadata = (data: Blob) => Promise<{
-    common: Partial<ContentMetadataTemplate<IPictureTemplate<Uint8Array | string>>>;
+    common: Partial<ContentMetadataTemplate<IPictureTemplate<PictureDataType>>>;
 }>;
 export type LoadingMediaProgress = {
     /**
      * - The current status of the operation.
      */
-    status: "loading" | "success";
+    status: 'loading' | 'success';
     /**
      * - The current execution stage.
      */
@@ -271,14 +128,14 @@ export type LoadingMediaProgress = {
     /**
      * - The current loading event.
      */
-    event?: ProgressEvent<EventTarget> | undefined;
+    event?: ProgressEvent<EventTarget>;
     /**
      * - The URL being processed.
      */
     url: string;
 };
-export type LoadingProgressStage = "INITIALIZING" | "DOWNLOADING" | "METADATA_LOADED" | "EXTRACTING_ID3" | "COMPLETE";
-export type LoadingErrorStage = "INITIALIZING" | "DOWNLOADING" | "METADATA" | "ID3" | "UNKNOWN";
+export type LoadingProgressStage = 'INITIALIZING' | 'DOWNLOADING' | 'METADATA_LOADED' | 'EXTRACTING_ID3' | 'COMPLETE';
+export type LoadingErrorStage = 'INITIALIZING' | 'DOWNLOADING' | 'METADATA' | 'ID3' | 'UNKNOWN';
 export type MediaLoadingErrorData = {
     /**
      * - The original error object.
@@ -293,4 +150,131 @@ export type MediaLoadingErrorData = {
      */
     stage: LoadingErrorStage;
 };
+/** @type {Map<string, number>} */
+export declare const _blobCounter: Map<string, number>;
+/**
+ * Returns a new object initialized with the default values for the core media content properties.
+ * @returns {MediaContentBase}
+ */
+export declare const getMediaContentBase: () => MediaContentBase;
+/**
+ * Returns a new object initialized with the default values for the media content metadata properties.
+ * @returns {MediaContentMetadata<PictureDataType>}
+ */
+export declare const getMediaContentMetadata: () => MediaContentMetadata<PictureDataType>;
+/**
+ * Custom error class to provide detailed context during the content preparation process.
+ * @extends Error
+ */
+export declare class MediaLoadingError extends Error {
+    url: string;
+    stage: LoadingErrorStage;
+    /**
+     * @param {string} message - Human-readable error message.
+     * @param {string} url - The URL that caused the error.
+     * @param {LoadingErrorStage} stage - The stage where the error occurred.
+     */
+    constructor(message: string, url: string, stage: LoadingErrorStage);
+}
+/**
+ * Internal helper to generate a deterministic ID from a string.
+ * @param {string} str
+ * @returns {Promise<string>}
+ * @private
+ */
+export declare const generateSimpleHash: (str: string) => Promise<string>;
+/**
+ * Helper to convert Uint8Array or Base64 string directly into a high performance Blob URL.
+ * @param {PictureDataType} data
+ * @param {string} format
+ * @returns {string} The generated Blob URL or original string if already valid.
+ */
+export declare const convertToBlobUrl: (data: PictureDataType, format?: string) => string;
+/**
+ * Asynchronous helper to convert a Blob URL back to Base64 (Date URL) at export time.
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
+export declare const blobUrlToBase64: (url: string) => Promise<string>;
+/**
+ * Safely revokes Blob URLs to prevent memory leaks from createObjectURL.
+ * @template {PictureDataType} PictureData
+ * @param {MediaContent<PictureData>} content
+ */
+export declare const revokeContentUrls: <PictureData extends PictureDataType>(content: MediaContent<PictureData>) => void;
+/**
+ * Helper to validate types within the media content metadata object.
+ * This ensures that if a property is present, it matches the expected type.
+ * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>} common
+ */
+export declare const valMediaContentMetadata: (common: ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>) => void;
+/**
+ * Helper to validate types within the media content metadata object.
+ * Allows the absence of properties (useful for updates/patch).
+ * @param {Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>} common
+ */
+export declare const valMediaContentMetadataPartial: (common: Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>) => void;
+/**
+ * Downloads an audio file from a URL and extracts its ID3/metadata tags.
+ *
+ * @param {string} url - The full URL of the audio file to be downloaded.
+ * @param {ParseMediaContentMetadata} parseFile - The function used to parse the file data.
+ * @returns {Promise<MediaContentMetadata<string>>} A promise that resolves to an object containing the extracted metadata.
+ * @throws {TypeError} If the provided `url` is not a string or `parseFile` is not a function.
+ * @throws {Error} If the network request fails or the parsing process encounters an error.
+ */
+export declare const extractMediaId3Tags: (url: string, parseFile: ParseMediaContentMetadata) => Promise<MediaContentMetadata<string>>;
+/**
+ * A Static Factory Method that prepares a MediaContent object by
+ * extracting metadata from an audio source.
+ *
+ * @template {PictureDataType} PictureData
+ * @param {string | HTMLMediaElement} source - A URL string or an existing Audio object.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [defaultMetadata={}] - Optional default metadata that overrides automatic extraction.
+ * @param {Partial<MediaContentBase & MediaContentMetadata<PictureData>> & { id?: string; weight?: number }} [metadata={}] - Optional manual metadata that overrides automatic extraction.
+ * @param {ParseMediaContentMetadata} [parseFile] - Private helper to interface with parseFile.
+ * @param {Object} [callbacks={}] - Callbacks for monitoring the loading process.
+ * @param {(progress: LoadingMediaProgress) => void} [callbacks.onProgress] - Callback triggered on stage changes.
+ * @param {(error: MediaLoadingErrorData) => void} [callbacks.onError] - Callback triggered when a non-fatal or fatal error occurs.
+ * @param {UnknownArtistGetter} unknownArtist
+ * @returns {Promise<MediaContent<PictureData>>} A promise that resolves to a valid MediaContent object.
+ * @throws {MediaLoadingError} If the preparation process fails at any stage.
+ *
+ * @example
+ * // Usage with URL
+ * import { parseBlob } from 'music-metadata';
+ * const track = await parseMediaMetadata('/assets/song.mp3', {}, { title: 'My Song', artist: 'Artist' }, parseBlob);
+ * media.add('music', track);
+ *
+ * @example
+ * // Usage with Audio Object
+ * import { parseBlob } from 'music-metadata';
+ * const audio = new Audio();
+ * audio.src = '/assets/song.mp3';
+ * const track = await parseMediaMetadata(audio, {}, {}, parseBlob);
+ * media.add('music', track);
+ *
+ * @example
+ * // Usage with tracking
+ * const track = await parseMediaMetadata(
+ *   '/assets/song.mp3',
+ *   {},
+ *   {},
+ *   parseBlob,
+ *   {
+ *     onProgress: (p) => console.log(`[${p.stage}] ${p.status}`),
+ *     onError: (e) => console.error(`Failed at ${e.stage} for ${e.url}: ${e.error.message}`)
+ *   }
+ * );
+ */
+export declare const parseMediaMetadata: <PictureData extends PictureDataType>(source: string | HTMLMediaElement, defaultMetadata?: Partial<MediaContentBase & MediaContentMetadata<PictureData>> & {
+    id?: string;
+    weight?: number;
+}, metadata?: Partial<MediaContentBase & MediaContentMetadata<PictureData>> & {
+    id?: string;
+    weight?: number;
+}, parseFile?: ParseMediaContentMetadata, callbacks?: {
+    onProgress?: (progress: LoadingMediaProgress) => void;
+    onError?: (error: MediaLoadingErrorData) => void;
+}, unknownArtist?: UnknownArtistGetter) => Promise<MediaContent<PictureData>>;
 //# sourceMappingURL=mediaContent.d.mts.map