tiny-essentials 1.26.4 → 1.27.0

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

@@ -0,0 +1,296 @@
+/**
+ * @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> = {
+    /**
+     * - The MIME type of the image (e.g., 'image/jpeg').
+     */
+    format: string;
+    /**
+     * - The raw binary data of the image.
+     */
+    data: PictureData;
+    /**
+     * - An optional textual description of the image.
+     */
+    description?: string | undefined;
+    /**
+     * - The specific type of picture (e.g., 'cover', 'front', 'back').
+     */
+    type?: string | undefined;
+    /**
+     * - The filename associated with the image.
+     */
+    name?: string | undefined;
+};
+/**
+ * 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>> = {
+    /**
+     * - The title of the track.
+     */
+    title: string | null;
+    /**
+     * - The name of the album.
+     */
+    album: string | null;
+    /**
+     * - The primary artist of the album.
+     */
+    albumartist: string | null;
+    /**
+     * - An array of artists associated with the album.
+     */
+    albumartists: string[];
+    /**
+     * - An array of genres associated with the track.
+     */
+    genre: string[];
+    /**
+     * - The record label.
+     */
+    label: string[];
+    /**
+     * - The composer of the track.
+     */
+    composer: string[];
+    /**
+     * - The release year.
+     */
+    year: number | null;
+    /**
+     * - The primary artist of the track.
+     */
+    artist: string | null;
+    /**
+     * - An array of artists associated with the track.
+     */
+    artists: string[];
+    /**
+     * - Disk information containing the current disk number and total disks.
+     */
+    disk: MediaNumber;
+    /**
+     * - Track information containing the current track number and total tracks.
+     */
+    track: MediaNumber;
+    /**
+     * - An array of picture objects containing album art.
+     */
+    picture?: IPictureContent[] | undefined;
+};
+/**
+ * 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 MediaContentBase = {
+    /**
+     * - Unique identifier.
+     */
+    id: string;
+    /**
+     * - Name of the track/message.
+     */
+    title: string;
+    /**
+     * - Artist or speaker name.
+     */
+    artist: string;
+    /**
+     * - Duration in milliseconds.
+     */
+    duration: number;
+    /**
+     * - Source URL/Path.
+     */
+    url: string;
+    /**
+     * - Probability multiplier for random selection mode.
+     */
+    weight?: number | undefined;
+};
+/**
+ * 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 ParseMediaContentMetadata = (data: Blob) => Promise<{
+    common: Partial<ContentMetadataTemplate<IPictureTemplate<Uint8Array | string>>>;
+}>;
+export type LoadingMediaProgress = {
+    /**
+     * - The current status of the operation.
+     */
+    status: "loading" | "success";
+    /**
+     * - The current execution stage.
+     */
+    stage: LoadingProgressStage;
+    /**
+     * - The current loading event.
+     */
+    event?: ProgressEvent<EventTarget> | undefined;
+    /**
+     * - 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 MediaLoadingErrorData = {
+    /**
+     * - The original error object.
+     */
+    error: Error;
+    /**
+     * - The URL that failed.
+     */
+    url: string;
+    /**
+     * - The stage where it failed.
+     */
+    stage: LoadingErrorStage;
+};
+//# sourceMappingURL=mediaContent.d.mts.map