tiny-essentials 1.28.12 → 1.28.15

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

@@ -1,7 +1,3 @@
-/**
- * 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
- */
 export type UnknownArtistGetter = string | (() => string);
 export type PictureDataType = Uint8Array | string;
 export type IPictureTemplate<PictureData extends PictureDataType> = {
@@ -28,62 +24,497 @@ export type IPictureTemplate<PictureData extends PictureDataType> = {
 };
 export type IPicture = IPictureTemplate<string>;
 export type MediaNumber = {
-    no: number | null;
-    of: number | null;
+    no?: number;
+    of?: number;
+};
+export type IComment = {
+    /**
+     * - A descriptor for the comment.
+     */
+    descriptor?: string;
+    /**
+     * - The language of the comment.
+     */
+    language?: string;
+    /**
+     * - The text content of the comment.
+     */
+    text?: string;
+};
+export type ILyricsText = {
+    /**
+     * - The lyric text content.
+     */
+    text?: string;
+    /**
+     * - The timestamp associated with this lyric line.
+     */
+    timestamp?: number;
+};
+export type TimestampFormat = {
+    /**
+     * - Indicates if the timestamp is not synchronized.
+     */
+    notSynchronized?: number;
+    /**
+     * - The MPEG frame number.
+     */
+    mpegFrameNumber?: number;
+    /**
+     * - The time in milliseconds.
+     */
+    milliseconds?: number;
+};
+export type LyricsContentType = {
+    /**
+     * - Content type for other.
+     */
+    other?: number;
+    /**
+     * - Content type for lyrics.
+     */
+    lyrics?: number;
+    /**
+     * - Content type for text.
+     */
+    text?: number;
+    /**
+     * - Content type for movement parts.
+     */
+    movement_part?: number;
+    /**
+     * - Content type for events.
+     */
+    events?: number;
+    /**
+     * - Content type for chords.
+     */
+    chord?: number;
+    /**
+     * - Content type for trivia/pop.
+     */
+    trivia_pop?: number;
+};
+export type ILyricsTag = {
+    /**
+     * - The text content of the lyrics.
+     */
+    text?: string;
+    /**
+     * - A descriptor for the lyrics.
+     */
+    descriptor?: string;
+    /**
+     * - The language of the lyrics.
+     */
+    language?: string;
+    /**
+     * - An array of synchronized lyric text objects.
+     */
+    syncText?: ILyricsText[];
+    /**
+     * - The format of the timestamp.
+     */
+    timeStampFormat?: TimestampFormat;
+    /**
+     * - The type of lyrical content.
+     */
+    contentType?: LyricsContentType;
+};
+export type IRating = {
+    /**
+     * - The source of the rating.
+     */
+    source?: string;
+    /**
+     * - The numeric rating value.
+     */
+    rating?: number;
 };
 export type ContentMetadataTemplate<IPictureContent extends IPictureTemplate<PictureDataType>> = {
+    _fetchData?: MediaContentFetchData<PictureDataType> | null;
     /**
      * - The title of the track.
      */
-    title: string | null;
+    title?: string;
     /**
      * - The name of the album.
      */
-    album: string | null;
+    album?: string;
     /**
      * - The primary artist of the album.
      */
-    albumartist: string | null;
+    albumartist?: string;
     /**
      * - An array of artists associated with the album.
      */
-    albumartists: string[];
+    albumartists?: string[];
     /**
      * - An array of genres associated with the track.
      */
-    genre: string[];
+    genre?: string[];
     /**
      * - The record label.
      */
-    label: string[];
+    label?: string[];
     /**
      * - The composer of the track.
      */
-    composer: string[];
+    composer?: string[];
     /**
      * - The release year.
      */
-    year: number | null;
+    year?: number;
     /**
      * - The primary artist of the track.
      */
-    artist: string | null;
+    artist?: string;
     /**
      * - An array of artists associated with the track.
      */
-    artists: string[];
+    artists?: string[];
     /**
      * - Disk information containing the current disk number and total disks.
      */
-    disk: MediaNumber;
+    disk?: MediaNumber;
     /**
      * - Track information containing the current track number and total tracks.
      */
-    track: MediaNumber;
+    track?: MediaNumber;
     /**
      * - An array of picture objects containing album art.
      */
     picture?: IPictureContent[];
+    /**
+     * - The date.
+     */
+    date?: string;
+    /**
+     * - The original date.
+     */
+    originaldate?: string;
+    /**
+     * - The original release year.
+     */
+    originalyear?: number;
+    /**
+     * - The release date.
+     */
+    releasedate?: string;
+    /**
+     * - An array of comments.
+     */
+    comment?: IComment[];
+    /**
+     * - An array of lyric tags.
+     */
+    lyrics?: ILyricsTag[];
+    /**
+     * - The sortable album name.
+     */
+    albumsort?: string;
+    /**
+     * - The sortable title.
+     */
+    titlesort?: string;
+    /**
+     * - The work/composition name.
+     */
+    work?: string;
+    /**
+     * - The sortable artist name.
+     */
+    artistsort?: string;
+    /**
+     * - The sortable album artist name.
+     */
+    albumartistsort?: string;
+    /**
+     * - The sortable composer name.
+     */
+    composersort?: string;
+    /**
+     * - An array of lyricists.
+     */
+    lyricist?: string[];
+    /**
+     * - An array of writers.
+     */
+    writer?: string[];
+    /**
+     * - An array of conductors.
+     */
+    conductor?: string[];
+    /**
+     * - An array of remixers.
+     */
+    remixer?: string[];
+    /**
+     * - An array of arrangers.
+     */
+    arranger?: string[];
+    /**
+     * - An array of engineers.
+     */
+    engineer?: string[];
+    /**
+     * - An array of publishers.
+     */
+    publisher?: string[];
+    /**
+     * - An array of producers.
+     */
+    producer?: string[];
+    /**
+     * - An array of DJ mixers.
+     */
+    djmixer?: string[];
+    /**
+     * - An array of mixers.
+     */
+    mixer?: string[];
+    /**
+     * - An array of technicians.
+     */
+    technician?: string[];
+    /**
+     * - The grouping name.
+     */
+    grouping?: string;
+    /**
+     * - An array of subtitles.
+     */
+    subtitle?: string[];
+    /**
+     * - An array of descriptions.
+     */
+    description?: string[];
+    /**
+     * - A long description.
+     */
+    longDescription?: string;
+    /**
+     * - An array of disc subtitles.
+     */
+    discsubtitle?: string[];
+    /**
+     * - Total number of tracks.
+     */
+    totaltracks?: string;
+    /**
+     * - Total number of discs.
+     */
+    totaldiscs?: string;
+    /**
+     * - Total number of movements.
+     */
+    movementTotal?: number;
+    /**
+     * - Whether it is a compilation.
+     */
+    compilation?: boolean;
+    /**
+     * - An array of ratings.
+     */
+    rating?: IRating[];
+    /**
+     * - Beats per minute.
+     */
+    bpm?: number;
+    /**
+     * - The mood of the track.
+     */
+    mood?: string;
+    /**
+     * - The media type.
+     */
+    media?: string;
+    /**
+     * - An array of catalog numbers.
+     */
+    catalognumber?: string[];
+    /**
+     * - The TV show name.
+     */
+    tvShow?: string;
+    /**
+     * - The sortable TV show name.
+     */
+    tvShowSort?: string;
+    /**
+     * - The TV season number.
+     */
+    tvSeason?: number;
+    /**
+     * - The TV episode number.
+     */
+    tvEpisode?: number;
+    /**
+     * - The TV episode ID.
+     */
+    tvEpisodeId?: string;
+    /**
+     * - The TV network.
+     */
+    tvNetwork?: string;
+    /**
+     * - Whether it is a podcast.
+     */
+    podcast?: boolean;
+    /**
+     * - The podcast URL.
+     */
+    podcasturl?: string;
+    /**
+     * - The release status.
+     */
+    releasestatus?: string;
+    /**
+     * - An array of release types.
+     */
+    releasetype?: string[];
+    /**
+     * - The release country.
+     */
+    releasecountry?: string;
+    /**
+     * - The script.
+     */
+    script?: string;
+    /**
+     * - The language.
+     */
+    language?: string;
+    /**
+     * - The copyright information.
+     */
+    copyright?: string;
+    /**
+     * - The license information.
+     */
+    license?: string;
+    /**
+     * - The encoder.
+     */
+    encodedby?: string;
+    /**
+     * - The encoder settings.
+     */
+    encodersettings?: string;
+    /**
+     * - Whether it is gapless.
+     */
+    gapless?: boolean;
+    /**
+     * - The barcode.
+     */
+    barcode?: string;
+    /**
+     * - An array of ISRC codes.
+     */
+    isrc?: string[];
+    /**
+     * - The ASIN.
+     */
+    asin?: string;
+    /**
+     * - The website.
+     */
+    website?: string;
+    /**
+     * - An array of performers and their instruments.
+     */
+    performer_instrument?: string[];
+    /**
+     * - The average loudness level.
+     */
+    averageLevel?: number;
+    /**
+     * - The peak loudness level.
+     */
+    peakLevel?: number;
+    /**
+     * - An array of notes.
+     */
+    notes?: string[];
+    /**
+     * - The original album.
+     */
+    originalalbum?: string;
+    /**
+     * - The original artist.
+     */
+    originalartist?: string;
+    /**
+     * - The initial key of the music in the file, e.g. "A Minor".
+     */
+    key?: string;
+    /**
+     * - An array of categories.
+     */
+    category?: string[];
+    /**
+     * - HD video flag.
+     */
+    hdVideo?: number;
+    /**
+     * - An array of keywords.
+     */
+    keywords?: string[];
+    /**
+     * - The movement.
+     */
+    movement?: string;
+    /**
+     * - The movement index.
+     */
+    movementIndex?: MediaNumber;
+    /**
+     * - The podcast ID.
+     */
+    podcastId?: string;
+    /**
+     * - Whether to show movement.
+     */
+    showMovement?: boolean;
+    /**
+     * - The stik value.
+     */
+    stik?: number;
+    /**
+     * - The play counter.
+     */
+    playCounter?: number;
+};
+export type MediaContentFetchNativeData = {
+    /**
+     * - The unique identifier for the native data.
+     */
+    id: string;
+    /**
+     * - The actual data value.
+     */
+    value?: any | Record<string | number | symbol, unknown>;
+};
+export type ICommonTagsResult<PictureData extends PictureDataType> = Record<string | number | symbol, unknown> & ContentMetadataTemplate<IPictureTemplate<PictureData>>;
+export type INativeTags = Record<string | number | symbol, MediaContentFetchNativeData[]>;
+export type MediaContentFetchData<PictureData extends PictureDataType> = {
+    /**
+     * - The common metadata properties.
+     */
+    common: ICommonTagsResult<PictureData>;
+    /**
+     * - The native metadata properties.
+     */
+    native: INativeTags;
+    /**
+     * - The format of the media.
+     */
+    format: unknown;
+    /**
+     * - The quality of the media.
+     */
+    quality: unknown;
 };
 export type MediaContentMetadata<PictureData extends PictureDataType> = ContentMetadataTemplate<IPictureTemplate<PictureData>>;
 export type MediaContentBase = {
@@ -117,9 +548,7 @@ export type MediaContentBase = {
     weight?: number;
 };
 export type MediaContent<PictureData extends PictureDataType> = MediaContentBase & MediaContentMetadata<PictureData>;
-export type ParseMediaContentMetadata = (data: Blob) => Promise<{
-    common: Partial<ContentMetadataTemplate<IPictureTemplate<PictureDataType>>>;
-}>;
+export type ParseMediaContentMetadata = (data: Blob) => Promise<MediaContentFetchData<PictureDataType>>;
 export type LoadingMediaProgress = {
     /**
      * - The current status of the operation.
@@ -161,11 +590,6 @@ export declare const _blobCounter: Map<string, number>;
  * @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
@@ -207,17 +631,16 @@ export declare const blobUrlToBase64: (url: string) => Promise<string>;
  */
 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
+ * @param {MediaContentFetchData<PictureDataType>|null} [fetchData] - The fetch object to be validated.
+ * @param {boolean} [returnsBoolean=false] - Ignores the throw error to return a boolean.
+ * @returns {boolean}
  */
-export declare const valMediaContentMetadata: (common: ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>) => void;
+export declare const valFetchMediaContent: (fetchData?: MediaContentFetchData<PictureDataType> | null, returnsBoolean?: boolean) => boolean;
 /**
- * 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
+ * Central logic of metadata validation.
+ * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array>>} common - The object to be validated.
  */
-export declare const valMediaContentMetadataPartial: (common: Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>) => void;
+export declare const valMediaContentMetadata: (common: ContentMetadataTemplate<IPictureTemplate<string | Uint8Array>>) => void;
 /**
  * Downloads an audio file from a URL and extracts its ID3/metadata tags.
  *