tiny-essentials 1.28.12 → 1.28.15

package/dist/v1/basics/mediaContent.mjs

@@ -1,3 +1,4 @@
+import { countObj, isJsonObject } from './objChecker.mjs';
 /**
  * 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
@@ -22,26 +23,165 @@
  */
 /**
  * A numeric structure representing track or disk indexing.
- * @typedef {{no: number|null, of: number|null}} MediaNumber
+ * @typedef {{no?: number, of?: number}} MediaNumber
+ */
+/**
+ * @typedef {Object} IComment
+ * @property {string} [descriptor] - A descriptor for the comment.
+ * @property {string} [language] - The language of the comment.
+ * @property {string} [text] - The text content of the comment.
+ */
+/**
+ * @typedef {Object} ILyricsText
+ * @property {string} [text] - The lyric text content.
+ * @property {number} [timestamp] - The timestamp associated with this lyric line.
+ */
+/**
+ * @typedef {Object} TimestampFormat
+ * @property {number} [notSynchronized] - Indicates if the timestamp is not synchronized.
+ * @property {number} [mpegFrameNumber] - The MPEG frame number.
+ * @property {number} [milliseconds] - The time in milliseconds.
+ */
+/**
+ * @typedef {Object} LyricsContentType
+ * @property {number} [other] - Content type for other.
+ * @property {number} [lyrics] - Content type for lyrics.
+ * @property {number} [text] - Content type for text.
+ * @property {number} [movement_part] - Content type for movement parts.
+ * @property {number} [events] - Content type for events.
+ * @property {number} [chord] - Content type for chords.
+ * @property {number} [trivia_pop] - Content type for trivia/pop.
+ */
+/**
+ * @typedef {Object} ILyricsTag
+ * @property {string} [text] - The text content of the lyrics.
+ * @property {string} [descriptor] - A descriptor for the lyrics.
+ * @property {string} [language] - The language of the lyrics.
+ * @property {ILyricsText[]} [syncText] - An array of synchronized lyric text objects.
+ * @property {TimestampFormat} [timeStampFormat] - The format of the timestamp.
+ * @property {LyricsContentType} [contentType] - The type of lyrical content.
+ */
+/**
+ * @typedef {Object} IRating
+ * @property {string} [source] - The source of the rating.
+ * @property {number} [rating] - The numeric rating value.
  */
 /**
  * This metadata structure is modeled template.
  *
  * @template {IPictureTemplate<PictureDataType>} 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 {MediaContentFetchData<PictureDataType>|null} [_fetchData]
+ * @property {string} [title] - The title of the track.
+ * @property {string} [album] - The name of the album.
+ * @property {string} [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} [year] - The release year.
+ * @property {string} [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.
+ * @property {string} [date] - The date.
+ * @property {string} [originaldate] - The original date.
+ * @property {number} [originalyear] - The original release year.
+ * @property {string} [releasedate] - The release date.
+ * @property {IComment[]} [comment] - An array of comments.
+ * @property {ILyricsTag[]} [lyrics] - An array of lyric tags.
+ * @property {string} [albumsort] - The sortable album name.
+ * @property {string} [titlesort] - The sortable title.
+ * @property {string} [work] - The work/composition name.
+ * @property {string} [artistsort] - The sortable artist name.
+ * @property {string} [albumartistsort] - The sortable album artist name.
+ * @property {string} [composersort] - The sortable composer name.
+ * @property {string[]} [lyricist] - An array of lyricists.
+ * @property {string[]} [writer] - An array of writers.
+ * @property {string[]} [conductor] - An array of conductors.
+ * @property {string[]} [remixer] - An array of remixers.
+ * @property {string[]} [arranger] - An array of arrangers.
+ * @property {string[]} [engineer] - An array of engineers.
+ * @property {string[]} [publisher] - An array of publishers.
+ * @property {string[]} [producer] - An array of producers.
+ * @property {string[]} [djmixer] - An array of DJ mixers.
+ * @property {string[]} [mixer] - An array of mixers.
+ * @property {string[]} [technician] - An array of technicians.
+ * @property {string} [grouping] - The grouping name.
+ * @property {string[]} [subtitle] - An array of subtitles.
+ * @property {string[]} [description] - An array of descriptions.
+ * @property {string} [longDescription] - A long description.
+ * @property {string[]} [discsubtitle] - An array of disc subtitles.
+ * @property {string} [totaltracks] - Total number of tracks.
+ * @property {string} [totaldiscs] - Total number of discs.
+ * @property {number} [movementTotal] - Total number of movements.
+ * @property {boolean} [compilation] - Whether it is a compilation.
+ * @property {IRating[]} [rating] - An array of ratings.
+ * @property {number} [bpm] - Beats per minute.
+ * @property {string} [mood] - The mood of the track.
+ * @property {string} [media] - The media type.
+ * @property {string[]} [catalognumber] - An array of catalog numbers.
+ * @property {string} [tvShow] - The TV show name.
+ * @property {string} [tvShowSort] - The sortable TV show name.
+ * @property {number} [tvSeason] - The TV season number.
+ * @property {number} [tvEpisode] - The TV episode number.
+ * @property {string} [tvEpisodeId] - The TV episode ID.
+ * @property {string} [tvNetwork] - The TV network.
+ * @property {boolean} [podcast] - Whether it is a podcast.
+ * @property {string} [podcasturl] - The podcast URL.
+ * @property {string} [releasestatus] - The release status.
+ * @property {string[]} [releasetype] - An array of release types.
+ * @property {string} [releasecountry] - The release country.
+ * @property {string} [script] - The script.
+ * @property {string} [language] - The language.
+ * @property {string} [copyright] - The copyright information.
+ * @property {string} [license] - The license information.
+ * @property {string} [encodedby] - The encoder.
+ * @property {string} [encodersettings] - The encoder settings.
+ * @property {boolean} [gapless] - Whether it is gapless.
+ * @property {string} [barcode] - The barcode.
+ * @property {string[]} [isrc] - An array of ISRC codes.
+ * @property {string} [asin] - The ASIN.
+ * @property {string} [website] - The website.
+ * @property {string[]} [performer_instrument] - An array of performers and their instruments.
+ * @property {number} [averageLevel] - The average loudness level.
+ * @property {number} [peakLevel] - The peak loudness level.
+ * @property {string[]} [notes] - An array of notes.
+ * @property {string} [originalalbum] - The original album.
+ * @property {string} [originalartist] - The original artist.
+ * @property {string} [key] - The initial key of the music in the file, e.g. "A Minor".
+ * @property {string[]} [category] - An array of categories.
+ * @property {number} [hdVideo] - HD video flag.
+ * @property {string[]} [keywords] - An array of keywords.
+ * @property {string} [movement] - The movement.
+ * @property {MediaNumber} [movementIndex] - The movement index.
+ * @property {string} [podcastId] - The podcast ID.
+ * @property {boolean} [showMovement] - Whether to show movement.
+ * @property {number} [stik] - The stik value.
+ * @property {number} [playCounter] - The play counter.
+ */
+/**
+ * @typedef {Object} MediaContentFetchNativeData
+ * @property {string} id - The unique identifier for the native data.
+ * @property {any|Record<string|number|symbol, unknown>} [value] - The actual data value.
+ */
+/**
+ * A record containing common metadata tags.
+ * @template {PictureDataType} PictureData
+ * @typedef {Record<string|number|symbol, unknown> & ContentMetadataTemplate<IPictureTemplate<PictureData>>} ICommonTagsResult
+ */
+/**
+ * A mapping of keys to arrays of native metadata fetch data.
+ * @typedef {Record<string|number|symbol, MediaContentFetchNativeData[]>} INativeTags
+ */
+/**
+ * @template {PictureDataType} PictureData
+ * @typedef {Object} MediaContentFetchData
+ * @property {ICommonTagsResult<PictureData>} common - The common metadata properties.
+ * @property {INativeTags} native - The native metadata properties.
+ * @property {unknown} format - The format of the media.
+ * @property {unknown} quality - The quality of the media.
  */
 /**
  * This metadata structure is modeled after the standard output of the
@@ -73,7 +213,7 @@
  * 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<PictureDataType>>> }>} A promise resolving to the common metadata properties.
+ * @returns {Promise<MediaContentFetchData<PictureDataType>>} A promise resolving to the common metadata properties.
  */
 /**
  * @typedef {Object} LoadingMediaProgress Represents the current state of a media loading operation, including its status, execution stage, and the URL being processed.
@@ -117,6 +257,27 @@ const checkObject = (/** @type {Object<string, any> | null} */ val, /** @type {s
         throw new TypeError(`Expected "${name}" to be a plain object, but received ${val === null ? 'null' : Array.isArray(val) ? 'array' : typeof val}.`);
     }
 };
+const isUndefinedAllowed = (/** @type {any} */ v, forceNoUndefined = false) => !forceNoUndefined && typeof v === 'undefined';
+const isString = (/** @type {string | null | undefined} */ v, forceNoUndefined = false) => isUndefinedAllowed(v, forceNoUndefined) ||
+    typeof v === 'string' ||
+    (!forceNoUndefined && v === null);
+const isNumber = (/** @type {number | null | undefined} */ v, forceNoUndefined = false) => isUndefinedAllowed(v, forceNoUndefined) ||
+    typeof v === 'number' ||
+    (!forceNoUndefined && v === null);
+const isBoolean = (/** @type {boolean | null | undefined} */ v, forceNoUndefined = false) => isUndefinedAllowed(v, forceNoUndefined) ||
+    typeof v === 'boolean' ||
+    (!forceNoUndefined && v === null);
+/**
+ * @template {any} T
+ * @param {T[]|undefined} v
+ * @param {(value: T) => boolean} valueValidator
+ */
+const isArray = (v, valueValidator) => {
+    if (isUndefinedAllowed(v))
+        return true;
+    checkFunction(valueValidator, 'valueValidator');
+    return Array.isArray(v) && v.every(valueValidator);
+};
 /** @type {Map<string, number>} */
 export const _blobCounter = new Map();
 /**
@@ -131,25 +292,6 @@ export const getMediaContentBase = () => ({
     duration: 0,
     weight: 1,
 });
-/**
- * Returns a new object initialized with the default values for the media content metadata properties.
- * @returns {MediaContentMetadata<PictureDataType>}
- */
-export const getMediaContentMetadata = () => ({
-    title: null,
-    album: null,
-    albumartist: null,
-    albumartists: [],
-    genre: [],
-    label: [],
-    composer: [],
-    year: null,
-    artist: null,
-    artists: [],
-    disk: { no: null, of: null },
-    track: { no: null, of: null },
-    picture: [],
-});
 /**
  * Custom error class to provide detailed context during the content preparation process.
  * @extends Error
@@ -267,50 +409,207 @@ export const revokeContentUrls = (content) => {
         });
     }
 };
+/**
+ * @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 const valFetchMediaContent = (fetchData, returnsBoolean = false) => {
+    if (isJsonObject(fetchData)) {
+        if (countObj(fetchData) !== 4) {
+            if (returnsBoolean)
+                return false;
+            throw new TypeError(`Invalid fetch data: Object must be an MediaContentFetchData.`);
+        }
+        valMediaContentMetadata(fetchData.common);
+        checkObject(fetchData.native, '_fetchData.native');
+        // @ts-ignore
+        checkObject(fetchData.format, '_fetchData.format');
+        // @ts-ignore
+        checkObject(fetchData.quality, '_fetchData.quality');
+        for (const id in fetchData.native) {
+            const item = fetchData.native[id];
+            if (!isArray(item, (data) => typeof data.id === 'string')) {
+                if (returnsBoolean)
+                    return false;
+                throw new TypeError(`Invalid native data: "${id}" must be an array of native fetch data.`);
+            }
+        }
+    }
+    return true;
+};
 /**
  * Central logic of metadata validation.
- * @param {Partial<ContentMetadataTemplate<IPictureTemplate<string | Uint8Array<ArrayBufferLike>>>>} common - The object to be validated.
- * @param {boolean} isPartial - If true, properties can be undefined.
+ * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array>>} common - The object to be validated.
  */
-const validateMediaContent = (common, isPartial) => {
+export const valMediaContentMetadata = (common) => {
     checkObject(common, 'common');
-    if (typeof isPartial !== 'boolean')
-        throw new TypeError('Expected "isPartial" to be a boolean.');
-    const isUndefinedAllowed = (/** @type {any} */ v) => isPartial && typeof v === 'undefined';
-    const isString = (/** @type {string | null | undefined} */ v) => isUndefinedAllowed(v) || typeof v === 'string' || v === null;
-    const isNumber = (/** @type {number | null | undefined}} */ v) => isUndefinedAllowed(v) || typeof v === 'number' || v === null;
-    const isArray = (
-    /** @type {string[] | IPictureTemplate<string|Uint8Array>[] | undefined} */ v, 
-    /** @type {(value: any, index: number, array: any[]) => any} */ valueValidator) => {
-        checkFunction(valueValidator, 'valueValidator');
-        if (isUndefinedAllowed(v))
-            return true;
-        if (Array.isArray(v) && v.every(valueValidator))
-            return true;
-        return false;
-    };
-    // Validate Primitives
+    valFetchMediaContent(common._fetchData);
+    // --- Primitive Validation ---
     if (!isString(common.title))
         throw new TypeError('Invalid metadata: "title" must be a string or null.');
     if (!isString(common.album))
         throw new TypeError('Invalid metadata: "album" must be a string or null.');
     if (!isString(common.albumartist))
-        throw new TypeError('Invalid metadata: "albumartist" must be a string or null.');
+        throw new TypeError('Invalid metadata: "albumartist" must be a a string or null.');
     if (!isString(common.artist))
         throw new TypeError('Invalid metadata: "artist" must be a string or null.');
+    if (!isBoolean(common.compilation))
+        throw new TypeError('Invalid metadata: "compilation" must be a boolean or null.');
+    if (!isBoolean(common.podcast))
+        throw new TypeError('Invalid metadata: "podcast" must be a boolean or null.');
+    if (!isBoolean(common.gapless))
+        throw new TypeError('Invalid metadata: "gapless" must be a boolean or null.');
+    if (!isBoolean(common.showMovement))
+        throw new TypeError('Invalid metadata: "showMovement" must be a boolean or null.');
+    if (!isNumber(common.averageLevel))
+        throw new TypeError('Invalid metadata: "averageLevel" must be a number or null.');
+    if (!isNumber(common.peakLevel))
+        throw new TypeError('Invalid metadata: "peakLevel" must be a number or null.');
+    if (!isNumber(common.hdVideo))
+        throw new TypeError('Invalid metadata: "hdVideo" must be a number or null.');
+    if (!isNumber(common.stik))
+        throw new TypeError('Invalid metadata: "stik" must be a number or null.');
+    if (!isNumber(common.playCounter))
+        throw new TypeError('Invalid metadata: "playCounter" must be a number or null.');
+    if (!isNumber(common.tvSeason))
+        throw new TypeError('Invalid metadata: "tvSeason" must be a number or null.');
+    if (!isNumber(common.tvEpisode))
+        throw new TypeError('Invalid metadata: "tvEpisode" must be a number or null.');
     if (!isNumber(common.year))
         throw new TypeError('Invalid metadata: "year" must be a number or null.');
+    if (!isNumber(common.bpm))
+        throw new TypeError('Invalid metadata: "bpm" must be a number or null.');
+    if (!isNumber(common.originalyear))
+        throw new TypeError('Invalid metadata: "originalyear" must be a number or null.');
+    if (!isNumber(common.movementTotal))
+        throw new TypeError('Invalid metadata: "movementTotal" must be a number or null.');
+    if (!isString(common.date))
+        throw new TypeError('Invalid metadata: "date" must be a string or null.');
+    if (!isString(common.originaldate))
+        throw new TypeError('Invalid metadata: "originaldate" must be a string or null.');
+    if (!isString(common.releasedate))
+        throw new TypeError('Invalid metadata: "releasedate" must be a string or null.');
+    if (!isString(common.albumsort))
+        throw new TypeError('Invalid metadata: "albumsort" must be a string or null.');
+    if (!isString(common.titlesort))
+        throw new TypeError('Invalid metadata: "titlesort" must be a string or null.');
+    if (!isString(common.work))
+        throw new TypeError('Invalid metadata: "work" must be a string or null.');
+    if (!isString(common.artistsort))
+        throw new TypeError('Invalid metadata: "artistsort" must be a string or null.');
+    if (!isString(common.albumartistsort))
+        throw new TypeError('Invalid metadata: "albumartistsort" must be a string or null.');
+    if (!isString(common.composersort))
+        throw new TypeError('Invalid metadata: "composersort" must be a string or null.');
+    if (!isString(common.grouping))
+        throw new TypeError('Invalid metadata: "grouping" must be a string or null.');
+    if (!isString(common.longDescription))
+        throw new TypeError('Invalid metadata: "longDescription" must be a string or null.');
+    if (!isString(common.totaltracks))
+        throw new TypeError('Invalid metadata: "totaltracks" must be a string or null.');
+    if (!isString(common.totaldiscs))
+        throw new TypeError('Invalid metadata: "totaldiscs" must be a string or null.');
+    if (!isString(common.mood))
+        throw new TypeError('Invalid metadata: "mood" must be a string or null.');
+    if (!isString(common.media))
+        throw new TypeError('Invalid metadata: "media" must be a string or null.');
+    if (!isString(common.tvShow))
+        throw new TypeError('Invalid metadata: "tvShow" must be a string or null.');
+    if (!isString(common.tvShowSort))
+        throw new TypeError('Invalid metadata: "tvShowSort" must be a string or null.');
+    if (!isString(common.tvEpisodeId))
+        throw new TypeError('Invalid metadata: "tvEpisodeId" must be a string or null.');
+    if (!isString(common.tvNetwork))
+        throw new TypeError('Invalid metadata: "tvNetwork" must be a string or null.');
+    if (!isString(common.podcasturl))
+        throw new TypeError('Invalid metadata: "podcasturl" must be a string or null.');
+    if (!isString(common.releasestatus))
+        throw new TypeError('Invalid metadata: "releasestatus" must be a string or null.');
+    if (!isString(common.releasecountry))
+        throw new TypeError('Invalid metadata: "releasecountry" must be a string or null.');
+    if (!isString(common.script))
+        throw new TypeError('Invalid metadata: "script" must be a string or null.');
+    if (!isString(common.language))
+        throw new TypeError('Invalid metadata: "language" must be a string or null.');
+    if (!isString(common.copyright))
+        throw new TypeError('Invalid metadata: "copyright" must be a string or null.');
+    if (!isString(common.license))
+        throw new TypeError('Invalid metadata: "license" must be a string or null.');
+    if (!isString(common.encodedby))
+        throw new TypeError('Invalid metadata: "encodedby" must be a string or null.');
+    if (!isString(common.encodersettings))
+        throw new TypeError('Invalid metadata: "encodersettings" must be a string or null.');
+    if (!isString(common.barcode))
+        throw new TypeError('Invalid metadata: "barcode" must be a string or null.');
+    if (!isString(common.asin))
+        throw new TypeError('Invalid metadata: "asin" must be a string or null.');
+    if (!isString(common.website))
+        throw new TypeError('Invalid metadata: "website" must be a string or null.');
+    if (!isString(common.originalalbum))
+        throw new TypeError('Invalid metadata: "originalalbum" must be a string or null.');
+    if (!isString(common.originalartist))
+        throw new TypeError('Invalid metadata: "originalartist" must be a string or null.');
+    if (!isString(common.key))
+        throw new TypeError('Invalid metadata: "key" must be a string or null.');
+    if (!isString(common.movement))
+        throw new TypeError('Invalid metadata: "movement" must be a string or null.');
+    if (!isString(common.podcastId))
+        throw new TypeError('Invalid metadata: "podcastId" must be a string or null.');
     // Validate Arrays
-    if (!isArray(common.albumartists, (value) => typeof value === 'string'))
-        throw new TypeError('Invalid metadata: "albumartists" must be an array of string.');
-    if (!isArray(common.genre, (value) => typeof value === 'string'))
-        throw new TypeError('Invalid metadata: "genre" must be an array of string.');
-    if (!isArray(common.label, (value) => typeof value === 'string'))
-        throw new TypeError('Invalid metadata: "label" must be an array of string.');
-    if (!isArray(common.composer, (value) => typeof value === 'string'))
-        throw new TypeError('Invalid metadata: "composer" must be an array of string.');
-    if (!isArray(common.artists, (value) => typeof value === 'string'))
-        throw new TypeError('Invalid metadata: "artists" must be an array of string.');
+    if (!isArray(common.albumartists, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "albumartists" must be an array of strings.');
+    if (!isArray(common.genre, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "genre" must be an array of strings.');
+    if (!isArray(common.label, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "label" must be an array of strings.');
+    if (!isArray(common.composer, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "composer" must be an array of strings.');
+    if (!isArray(common.artists, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "artists" must be an array of strings.');
+    if (!isArray(common.lyricist, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "lyricist" must be an array of strings.');
+    if (!isArray(common.writer, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "writer" must be an array of strings.');
+    if (!isArray(common.conductor, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "conductor" must be an array of strings.');
+    if (!isArray(common.remixer, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "remixer" must be an array of strings.');
+    if (!isArray(common.arranger, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "arranger" must be an array of strings.');
+    if (!isArray(common.engineer, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "engineer" must be an array of strings.');
+    if (!isArray(common.publisher, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "publisher" must be an array of strings.');
+    if (!isArray(common.producer, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "producer" must be an array of strings.');
+    if (!isArray(common.djmixer, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "djmixer" must be an array of strings.');
+    if (!isArray(common.mixer, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "mixer" must be an array of strings.');
+    if (!isArray(common.technician, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "technician" must be an array of strings.');
+    if (!isArray(common.subtitle, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "subtitle" must be an array of strings.');
+    if (!isArray(common.description, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "description" must be an array of strings.');
+    if (!isArray(common.discsubtitle, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "discsubtitle" must be an array of strings.');
+    if (!isArray(common.releasetype, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "releasetype" must be an array of strings.');
+    if (!isArray(common.isrc, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "isrc" must be an array of strings.');
+    if (!isArray(common.performer_instrument, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "performer_instrument" must be an array of strings.');
+    if (!isArray(common.notes, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "notes" must be an array of strings.');
+    if (!isArray(common.category, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "category" must be an array of strings.');
+    if (!isArray(common.keywords, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "keywords" must be an array of strings.');
+    if (!isArray(common.catalognumber, (v) => typeof v === 'string'))
+        throw new TypeError('Invalid metadata: "catalognumber" must be an array of strings.');
+    // Validate Complex Arrays
     if (!isArray(common.picture, (value) => value &&
         typeof value === 'object' &&
         (typeof value.description === 'undefined' || typeof value.description === 'string') &&
@@ -319,18 +618,53 @@ const validateMediaContent = (common, isPartial) => {
         typeof value.format === 'string' &&
         (value.data instanceof Uint8Array || typeof value.data === 'string')))
         throw new TypeError('Invalid metadata: "picture" must be an array of pictures.');
+    if (!isArray(common.comment, (v) => v !== null &&
+        typeof v === 'object' &&
+        isString(v.descriptor) &&
+        isString(v.language) &&
+        isString(v.text)))
+        throw new TypeError('Invalid metadata: "comment" must be an array of valid IComment objects.');
+    if (!isArray(common.lyrics, (v) => {
+        const isLyricsContentType = (/** @type {LyricsContentType|null|undefined} */ v) => v === undefined ||
+            (v !== null &&
+                typeof v === 'object' &&
+                isNumber(v.other) &&
+                isNumber(v.lyrics) &&
+                isNumber(v.text) &&
+                isNumber(v.movement_part) &&
+                isNumber(v.events) &&
+                isNumber(v.chord) &&
+                isNumber(v.trivia_pop));
+        const isTimestampFormat = (/** @type {TimestampFormat|null|undefined} */ v) => v === undefined ||
+            (v !== null &&
+                typeof v === 'object' &&
+                isNumber(v.notSynchronized) &&
+                isNumber(v.mpegFrameNumber) &&
+                isNumber(v.milliseconds));
+        return (v !== null &&
+            typeof v === 'object' &&
+            isString(v.text) &&
+            isString(v.descriptor) &&
+            isString(v.language) &&
+            (!Array.isArray(v) ||
+                isArray(v.syncText, (v) => v !== null && typeof v === 'object' && isString(v.text) && isNumber(v.timestamp))) &&
+            isTimestampFormat(v.timeStampFormat) &&
+            isLyricsContentType(v.contentType));
+    }))
+        throw new TypeError('Invalid metadata: "lyrics" must be an array of valid ILyricsTag objects.');
+    if (!isArray(common.rating, (v) => v !== null && typeof v === 'object' && isString(v.source) && isNumber(v.rating)))
+        throw new TypeError('Invalid metadata: "rating" must be an array of valid IRating objects.');
+    // Validate Nested Objects (Disk, Track, Movement, etc.)
     /**
      * Validate Nested Objects (Disk and Track)
      * @param {string} name
      * @param {MediaNumber|null} [info]
      */
     const validateTrackInfo = (name, info) => {
-        checkString(name, 'name');
         if (isUndefinedAllowed(info))
-            return; // Ignores if partial
-        if (info === undefined || info === null) {
-            throw new TypeError(`Invalid metadata: "${name}" is required.`);
-        }
+            return;
+        if (info === null)
+            return;
         if (typeof info !== 'object')
             throw new TypeError(`Invalid metadata: "${name}" must be an object or null.`);
         if (typeof info.no !== 'number' && info.no !== null)
@@ -340,24 +674,7 @@ const validateMediaContent = (common, isPartial) => {
     };
     validateTrackInfo('disk', common.disk);
     validateTrackInfo('track', common.track);
-};
-/**
- * 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 const valMediaContentMetadata = (common) => {
-    checkObject(common, 'common');
-    return validateMediaContent(common, false);
-};
-/**
- * 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 const valMediaContentMetadataPartial = (common) => {
-    checkObject(common, 'common');
-    return validateMediaContent(common, true);
+    validateTrackInfo('movementIndex', common.movementIndex);
 };
 /**
  * Downloads an audio file from a URL and extracts its ID3/metadata tags.
@@ -373,45 +690,164 @@ export const extractMediaId3Tags = async (url, parseFile, convertBase64toBlob =
     // Argument Validation
     checkString(url, 'url');
     checkFunction(parseFile, 'parseFile');
-    try {
-        // 1. Download the file from the provided URL
-        const response = await fetch(url);
-        if (!response.ok)
-            throw new Error(`Failed to fetch audio file: ${response.status} ${response.statusText}`);
-        // 2. Convert the response into a Blob so the parser can read it
-        const blob = await response.blob();
-        // 3. Use the provided parser function on the Blob
-        const metadata = await parseFile(blob);
-        // 4. Complete Validation of the parsed metadata structure
-        if (!metadata || typeof metadata.common !== 'object')
-            throw new TypeError('Invalid metadata: "common" property is missing or not an object.');
-        const common = metadata.common;
-        valMediaContentMetadataPartial(common);
-        // 5. Return the specific metadata fields requested
-        // We structure the return to match the MediaContentMetadata typedef
-        return {
-            title: common?.title ?? null,
-            album: common?.album ?? null,
-            albumartist: common?.albumartist ?? null,
-            albumartists: common?.albumartists ?? [],
-            genre: common?.genre ?? [],
-            label: common?.label ?? [],
-            composer: common?.composer ?? [],
-            year: common?.year ?? null,
-            artist: common?.artist ?? null,
-            artists: common?.artists ?? [],
-            disk: common?.disk ? { no: common.disk.no, of: common.disk.of } : { no: null, of: null },
-            track: common?.track ? { no: common.track.no, of: common.track.of } : { no: null, of: null },
-            picture: common?.picture?.map((value) => ({
-                ...value,
-                data: convertBase64toBlob ? convertToBlobUrl(value.data, value.format) : value.data,
-            })) ?? [],
-        };
-    }
-    catch (error) {
-        // Re-throwing the error allows the caller to handle specific failure cases
-        throw error;
+    // 1. Download the file from the provided URL
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch audio file: ${response.status} ${response.statusText}`);
+    // 2. Convert the response into a Blob so the parser can read it
+    const blob = await response.blob();
+    // 3. Use the provided parser function on the Blob to read metadata
+    const metadata = await parseFile(blob);
+    // 4. Complete Validation of the parsed metadata structure
+    if (!metadata || typeof metadata.common !== 'object')
+        throw new TypeError('Invalid metadata: "common" property is missing.');
+    if (typeof metadata.common['performer:instrument'] !== undefined)
+        // @ts-ignore
+        metadata.common.performer_instrument = metadata.common['performer:instrument'];
+    valFetchMediaContent(metadata);
+    const common = metadata.common;
+    valMediaContentMetadata(common);
+    /**
+     * @type {(value: [string, any]) => boolean}
+     */
+    const filterContent = ([_, value]) => Array.isArray(value)
+        ? value.length > 0
+        : isJsonObject(value)
+            ? (() => {
+                value;
+                const d = Object.fromEntries(Object.entries(value).filter(filterContent));
+                const amount = countObj(d);
+                return amount > 0;
+            })()
+            : value !== null;
+    // Fix blob values.
+    const picture = common?.picture?.map((value) => ({
+        ...value,
+        data: convertBase64toBlob ? convertToBlobUrl(value.data, value.format) : value.data,
+    })) ?? [];
+    metadata.common = {
+        ...metadata.common,
+        picture: picture.map((value) => ({
+            ...value,
+            data: '',
+        })),
+    };
+    // Sanitize metadata.native to prevent Uint8Array leakage
+    if (convertBase64toBlob) {
+        Object.keys(metadata.native).forEach((key) => {
+            metadata.native[key] = metadata.native[key].map((item) => {
+                // Check if item.value is an object and contains a 'data' property that is a Uint8Array
+                if (item.value && typeof item.value === 'object' && item.value.data instanceof Uint8Array) {
+                    const index = common?.picture?.findIndex((item2) => item2.data === item.value.data &&
+                        item2.format === item.value.format &&
+                        item2.description === item.value.description &&
+                        item2.name === item.value.name) ?? -1;
+                    const data = picture[index];
+                    if (data) {
+                        return { ...item, value: { ...item.value, data: '' } };
+                    }
+                }
+                return item;
+            });
+        });
     }
+    // 5. Return the specific metadata fields requested
+    // We structure the return to match the MediaContentMetadata typedef
+    /** @type {MediaContentMetadata<PictureDataType>} */
+    const result = Object.fromEntries(Object.entries({
+        title: common?.title ?? null,
+        album: common?.album ?? null,
+        albumartist: common?.albumartist ?? null,
+        albumartists: common?.albumartists ?? [],
+        genre: common?.genre ?? [],
+        label: common?.label ?? [],
+        composer: common?.composer ?? [],
+        year: common?.year ?? null,
+        artist: common?.artist ?? null,
+        artists: common?.artists ?? [],
+        disk: common?.disk ? { no: common.disk.no, of: common.disk.of } : null,
+        track: common?.track ? { no: common.track.no, of: common.track.of } : null,
+        movementIndex: common?.movementIndex
+            ? { no: common.movementIndex.no, of: common.movementIndex.of }
+            : null,
+        picture,
+        date: common?.date ?? null,
+        originaldate: common?.originaldate ?? null,
+        originalyear: common?.originalyear ?? null,
+        releasedate: common?.releasedate ?? null,
+        comment: common?.comment ?? [],
+        lyrics: common?.lyrics ?? [],
+        albumsort: common?.albumsort ?? null,
+        titlesort: common?.titlesort ?? null,
+        work: common?.work ?? null,
+        artistsort: common?.artistsort ?? null,
+        albumartistsort: common?.albumartistsort ?? null,
+        composersort: common?.composersort ?? null,
+        lyricist: common?.lyricist ?? [],
+        writer: common?.writer ?? [],
+        conductor: common?.conductor ?? [],
+        remixer: common?.remixer ?? [],
+        arranger: common?.arranger ?? [],
+        engineer: common?.engineer ?? [],
+        publisher: common?.publisher ?? [],
+        producer: common?.producer ?? [],
+        djmixer: common?.djmixer ?? [],
+        mixer: common?.mixer ?? [],
+        technician: common?.technician ?? [],
+        grouping: common?.grouping ?? null,
+        subtitle: common?.subtitle ?? [],
+        description: common?.description ?? [],
+        longDescription: common?.longDescription ?? null,
+        discsubtitle: common?.discsubtitle ?? [],
+        totaltracks: common?.totaltracks ?? null,
+        totaldiscs: common?.totaldiscs ?? null,
+        movementTotal: common?.movementTotal ?? null,
+        compilation: common?.compilation ?? null,
+        rating: common?.rating ?? [],
+        bpm: common?.bpm ?? null,
+        mood: common?.mood ?? null,
+        media: common?.media ?? null,
+        catalognumber: common?.catalognumber ?? [],
+        tvShow: common?.tvShow ?? null,
+        tvShowSort: common?.tvShowSort ?? null,
+        tvSeason: common?.tvSeason ?? null,
+        tvEpisode: common?.tvEpisode ?? null,
+        tvEpisodeId: common?.tvEpisodeId ?? null,
+        tvNetwork: common?.tvNetwork ?? null,
+        podcast: common?.podcast ?? null,
+        podcasturl: common?.podcasturl ?? null,
+        releasestatus: common?.releasestatus ?? null,
+        releasetype: common?.releasetype ?? [],
+        releasecountry: common?.releasecountry ?? null,
+        script: common?.script ?? null,
+        language: common?.language ?? null,
+        copyright: common?.copyright ?? null,
+        license: common?.license ?? null,
+        encodedby: common?.encodedby ?? null,
+        encodersettings: common?.encodersettings ?? null,
+        gapless: common?.gapless ?? null,
+        barcode: common?.barcode ?? null,
+        isrc: common?.isrc ?? [],
+        asin: common?.asin ?? null,
+        website: common?.website ?? null,
+        performer_instrument: common?.performer_instrument ?? [],
+        averageLevel: common?.averageLevel ?? null,
+        peakLevel: common?.peakLevel ?? null,
+        notes: common?.notes ?? [],
+        originalalbum: common?.originalalbum ?? null,
+        originalartist: common?.originalartist ?? null,
+        key: common?.key ?? null,
+        category: common?.category ?? [],
+        hdVideo: common?.hdVideo ?? null,
+        keywords: common?.keywords ?? [],
+        movement: common?.movement ?? null,
+        podcastId: common?.podcastId ?? null,
+        showMovement: common?.showMovement ?? null,
+        stik: common?.stik ?? null,
+        playCounter: common?.playCounter ?? null,
+    }).filter(filterContent));
+    result._fetchData = metadata;
+    return result;
 };
 /**
  * A Static Factory Method that prepares a MediaContent object by
@@ -460,7 +896,7 @@ export const extractMediaId3Tags = async (url, parseFile, convertBase64toBlob =
 export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata = {}, parseFile = (data) => {
     if (!(data instanceof Blob))
         throw new TypeError('Expected "data" to be a Blob.');
-    return new Promise((resolve, reject) => reject(new TypeError('parseFile library not found.')));
+    return new Promise((_, reject) => reject(new TypeError('parseFile library not found.')));
 }, callbacks = {}, convertBase64toBlob = true, unknownArtist = 'null') => {
     // Argument Validation
     if (typeof source !== 'string' && !(source instanceof HTMLMediaElement))
@@ -501,10 +937,10 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
     const notifyError = (/** @type {Error} */ error, /** @type {LoadingErrorStage} */ stage) => {
         if (!(error instanceof Error))
             throw new TypeError('Expected "error" to be an Error.');
-        checkString(stage, 'stage'); // Adicionado
+        checkString(stage, 'stage');
         if (callbacks.onError) {
             callbacks.onError({
-                error,
+                error: error instanceof Error ? error : new Error(String(error)),
                 url: url || (source instanceof HTMLMediaElement ? source.src : 'unknown'),
                 stage,
             });
@@ -596,11 +1032,36 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
         };
         // 5. Final Merge Logic
         // Priority: Manual Metadata (highest) > Extracted ID3 > Default values
+        /**
+         * @template {Partial<MediaContent<PictureData>>} Metadata
+         * @param {Metadata} meta
+         */
+        const mergeMetadata = (meta) => {
+            const metadataEdit = { ...meta };
+            if (isJsonObject(metadataEdit._fetchData)) {
+                if (isJsonObject(extractedMetadata._fetchData)) {
+                    metadataEdit._fetchData = {
+                        ...extractedMetadata._fetchData,
+                    };
+                }
+                if (isJsonObject(meta._fetchData)) {
+                    if (typeof meta._fetchData.common !== 'undefined')
+                        metadataEdit._fetchData.common = meta._fetchData.common;
+                    if (typeof meta._fetchData.native !== 'undefined')
+                        metadataEdit._fetchData.native = meta._fetchData.native;
+                    if (typeof meta._fetchData.format !== 'undefined')
+                        metadataEdit._fetchData.format = meta._fetchData.format;
+                    if (typeof meta._fetchData.quality !== 'undefined')
+                        metadataEdit._fetchData.quality = meta._fetchData.quality;
+                }
+            }
+            return metadataEdit;
+        };
         const finalContent = {
             ...baseData,
-            ...defaultMetadata,
+            ...mergeMetadata(defaultMetadata),
             ...extractedMetadata,
-            ...metadata,
+            ...mergeMetadata(metadata),
             // Explicitly ensure title and artist are resolved from the hierarchy
             title: extractedMetadata.title || metadata.title || getFallbackTitleFromUrl(url),
             artist: extractedMetadata.artist ||
@@ -609,24 +1070,17 @@ export const parseMediaMetadata = async (source, defaultMetadata = {}, metadata
         };
         // Notify Success
         if (callbacks.onProgress) {
-            callbacks.onProgress({
-                status: 'success',
-                stage: 'COMPLETE',
-                url: url,
-            });
+            callbacks.onProgress({ status: 'success', stage: 'COMPLETE', url: url });
         }
         return /** @type {MediaContent<PictureData>} */ (finalContent);
     }
     catch (err) {
         // If it's already a MediaLoadingError, re-throw it.
         // Otherwise, wrap it.
-        if (err instanceof MediaLoadingError) {
+        if (err instanceof MediaLoadingError)
             throw err;
-        }
-        else {
-            const wrappedError = new MediaLoadingError(err instanceof Error ? err.message : 'UNKNOWN ERROR', url, 'INITIALIZING');
-            notifyError(wrappedError, 'INITIALIZING');
-            throw wrappedError;
-        }
+        const wrappedError = new MediaLoadingError(err instanceof Error ? err.message : 'UNKNOWN ERROR', url, 'INITIALIZING');
+        notifyError(wrappedError, 'INITIALIZING');
+        throw wrappedError;
     }
 };