tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
296 lines • 10.2 kB
text/typescript
/**
* @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