tiny-essentials 1.28.12 → 1.28.15

package/dist/v1/basics/mediaContent.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var objChecker = require('./objChecker.cjs');
+
 /**
  * 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
@@ -28,7 +30,54 @@
 
 /**
  * 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.
  */
 
 /**
@@ -36,19 +85,121 @@
  *
  * @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.
  */
 
 /**
@@ -85,7 +236,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.
  */
 
 /**
@@ -137,6 +288,35 @@ const checkObject = (/** @type {Object<string, any> | null} */ val, /** @type {s
   }
 };
 
+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>} */
 const _blobCounter = new Map();
 
@@ -153,26 +333,6 @@ const getMediaContentBase = () => ({
   weight: 1,
 });
 
-/**
- * Returns a new object initialized with the default values for the media content metadata properties.
- * @returns {MediaContentMetadata<PictureDataType>}
- */
-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
@@ -298,55 +458,213 @@ const revokeContentUrls = (content) => {
 };
 
 /**
- * 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 {MediaContentFetchData<PictureDataType>|null} [fetchData] - The fetch object to be validated.
+ * @param {boolean} [returnsBoolean=false] - Ignores the throw error to return a boolean.
+ * @returns {boolean}
  */
-const validateMediaContent = (common, isPartial) => {
-  checkObject(common, 'common');
-  if (typeof isPartial !== 'boolean') throw new TypeError('Expected "isPartial" to be a boolean.');
+const valFetchMediaContent = (fetchData, returnsBoolean = false) => {
+  if (objChecker.isJsonObject(fetchData)) {
+    if (objChecker.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');
 
-  const isUndefinedAllowed = (/** @type {any} */ v) => isPartial && typeof v === 'undefined';
+    // @ts-ignore
+    checkObject(fetchData.format, '_fetchData.format');
+    // @ts-ignore
+    checkObject(fetchData.quality, '_fetchData.quality');
 
-  const isString = (/** @type {string | null | undefined} */ v) =>
-    isUndefinedAllowed(v) || typeof v === 'string' || v === null;
+    for (const id in fetchData.native) {
+      const item = fetchData.native[id];
 
-  const isNumber = (/** @type {number | null | undefined}} */ v) =>
-    isUndefinedAllowed(v) || typeof v === 'number' || v === null;
+      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;
+};
 
-  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;
-  };
+/**
+ * Central logic of metadata validation.
+ * @param {ContentMetadataTemplate<IPictureTemplate<string | Uint8Array>>} common - The object to be validated.
+ */
+const valMediaContentMetadata = (common) => {
+  checkObject(common, 'common');
+  valFetchMediaContent(common._fetchData);
+
+  // --- Primitive Validation ---
 
-  // Validate Primitives
   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,
@@ -362,19 +680,77 @@ const validateMediaContent = (common, isPartial) => {
   )
     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.`);
-    }
-
+    if (isUndefinedAllowed(info)) 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)
@@ -385,26 +761,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
- */
-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
- */
-const valMediaContentMetadataPartial = (common) => {
-  checkObject(common, 'common');
-  return validateMediaContent(common, true);
+  validateTrackInfo('movementIndex', common.movementIndex);
 };
 
 /**
@@ -422,29 +779,87 @@ const extractMediaId3Tags = async (url, parseFile, convertBase64toBlob = true) =
   checkString(url, 'url');
   checkFunction(parseFile, 'parseFile');
 
-  try {
-    // 1. Download the file from the provided URL
-    const response = await fetch(url);
+  // 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}`);
+  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();
+  // 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);
 
-    // 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.');
+  if (typeof metadata.common['performer:instrument'] !== undefined)
+    // @ts-ignore
+    metadata.common.performer_instrument = metadata.common['performer:instrument'];
+  valFetchMediaContent(metadata);
 
-    // 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;
+  valMediaContentMetadata(common);
 
-    const common = metadata.common;
-    valMediaContentMetadataPartial(common);
+  /**
+   * @type {(value: [string, any]) => boolean}
+   */
+  const filterContent = ([_, value]) =>
+    Array.isArray(value)
+      ? value.length > 0
+      : objChecker.isJsonObject(value)
+        ? (() => {
+            const d = Object.fromEntries(Object.entries(value).filter(filterContent));
+            const amount = objChecker.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: '',
+    })),
+  };
 
-    // 5. Return the specific metadata fields requested
-    // We structure the return to match the MediaContentMetadata typedef
-    return {
+  // 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,
@@ -455,18 +870,91 @@ const extractMediaId3Tags = async (url, parseFile, convertBase64toBlob = true) =
       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;
-  }
+      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;
 };
 
 /**
@@ -519,7 +1007,7 @@ const parseMediaMetadata = async (
   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,
@@ -570,11 +1058,11 @@ const parseMediaMetadata = async (
 
   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,
       });
@@ -678,11 +1166,38 @@ const parseMediaMetadata = async (
 
     // 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 (objChecker.isJsonObject(metadataEdit._fetchData)) {
+        if (objChecker.isJsonObject(extractedMetadata._fetchData)) {
+          metadataEdit._fetchData = {
+            ...extractedMetadata._fetchData,
+          };
+        }
+        if (objChecker.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:
@@ -693,28 +1208,21 @@ const parseMediaMetadata = async (
 
     // 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) {
-      throw err;
-    } else {
-      const wrappedError = new MediaLoadingError(
-        err instanceof Error ? err.message : 'UNKNOWN ERROR',
-        url,
-        'INITIALIZING',
-      );
-      notifyError(wrappedError, 'INITIALIZING');
-      throw wrappedError;
-    }
+    if (err instanceof MediaLoadingError) throw err;
+    const wrappedError = new MediaLoadingError(
+      err instanceof Error ? err.message : 'UNKNOWN ERROR',
+      url,
+      'INITIALIZING',
+    );
+    notifyError(wrappedError, 'INITIALIZING');
+    throw wrappedError;
   }
 };
 
@@ -725,8 +1233,7 @@ exports.convertToBlobUrl = convertToBlobUrl;
 exports.extractMediaId3Tags = extractMediaId3Tags;
 exports.generateSimpleHash = generateSimpleHash;
 exports.getMediaContentBase = getMediaContentBase;
-exports.getMediaContentMetadata = getMediaContentMetadata;
 exports.parseMediaMetadata = parseMediaMetadata;
 exports.revokeContentUrls = revokeContentUrls;
+exports.valFetchMediaContent = valFetchMediaContent;
 exports.valMediaContentMetadata = valMediaContentMetadata;
-exports.valMediaContentMetadataPartial = valMediaContentMetadataPartial;