\n\n[sponsor-badge]: https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2\n[sponsor-url]: https://github.com/sponsors/alessiofrittoli\n\n### Table of Contents\n\n- [Getting started](#getting-started)\n- [API Reference](#api-reference)\n - [MIME types](#mime-types)\n - [MediaSession](#mediasession)\n - [AudioEngine](#audioengine)\n - [Audio Engine Manager](#audio-engine-manager)\n - [Audio Utilities](#audio-utilities)\n - [Media Playback](#media-playback)\n - [Image Video Stream](#image-video-stream)\n - [Media Artwork Picture-in-Picture](#media-artwork-picture-in-picture)\n - [Utilities](#utilities)\n- [Development](#development)\n - [Install depenendencies](#install-depenendencies)\n - [Build the source code](#build-the-source-code)\n - [ESLint](#eslint)\n - [Jest](#jest)\n- [Contributing](#contributing)\n- [Security](#security)\n- [Credits](#made-with-)\n\n---\n\n### Getting started\n\nRun the following command to start using `media-utils` in your projects:\n\n```bash\nnpm i @alessiofrittoli/media-utils\n```\n\nor using `pnpm`\n\n```bash\npnpm i @alessiofrittoli/media-utils\n```\n\n---\n\n### API Reference\n\n#### MIME types\n\n##### `getMimeType()`\n\nGet the MIME type from the given `input` string.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |\n| `input` | `string` | The input string where MIME type is extracted from. |\n| `type` | `MediaType` | (Optional) Accepted media type. This may be usefull when subtype matches other media types (eg. `audio/mp4` - `video/mp4`). |\n\n\n\n---\n\n\n\nReturns\n\nType: `MIMEType`\n\n- The MIME type if found.\n- `undefined` otherwise.\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { getMimeType } from \"@alessiofrittoli/media-utils\";\n\nconsole.log(getMimeType(\"/path/to/video-file.mp4\")); // Outputs: 'video/mp4'\nconsole.log(getMimeType(\"/path/to/audio-file.mp4\", \"audio\")); // Outputs: 'audio/mp4'\nconsole.log(getMimeType(\"/path/to/audio-file.mp3\")); // Outputs: 'audio/mpeg'\n```\n\n\n\n---\n\n##### `getAllowedMimeTypes()`\n\nGet allowed MIME types.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `accept` | `string` | (Optioanl) A string describing allowed MIME types. |\n| | | The format is the same accepted by [`HTMLInputElement.accept`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/accept) attribute. |\n| | | It could be one of the following examples: |\n| | | - `*` |\n| | | - `image` (type) |\n| | | - `image/*` ({type}/{subtype}) |\n| | | - `image/png` ({type}/{subtype}) - specific |\n| | | - `.png` (extension) |\n| | | - `image,audio` (multiple types) |\n| | | - `image/*,audio/*` (multiple {type}/{subtype}) |\n| | | - `.png, .mp3` (multiple extensions) |\n| | | - `.docx, audio, video/*, text/html` (mixed) |\n\n\n\n---\n\n\n\nReturns\n\nType: `(MIMEType | '*')[]`\n\nAn array of MIME types based on the `accept` value. `[ '*' ]` if a wildcard or no `accept` is given.\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { getAllowedMimeTypes } from \"@alessiofrittoli/media-utils\";\n\nconsole.log(getAllowedMimeTypes());\nconsole.log(getAllowedMimeTypes(\"*\"));\nconsole.log(getAllowedMimeTypes(\"image\"));\nconsole.log(getAllowedMimeTypes(\"audio/*\"));\nconsole.log(getAllowedMimeTypes(\"image,video\"));\nconsole.log(getAllowedMimeTypes(\"image/*,video/*\"));\nconsole.log(getAllowedMimeTypes(\".mp3,mp4\"));\nconsole.log(getAllowedMimeTypes(\".jpg, .png\"));\nconsole.log(getAllowedMimeTypes(\"image/jpeg,.jpg\"));\n```\n\n\n\n---\n\n#### MediaSession\n\n##### Types\n\n###### `MediaArtWork`\n\nThe Media Artwork.\n\nCompatible type with the global `MediaImage` interface.\n\n\n\nProperties\n\n| Property | Type | Description |\n| -------- | ---------- | --------------------------------------------------------------------------------------------------- |\n| `src` | `UrlInput` | The Media Artwork image URL. |\n| | | See [`UrlInput`](https://npmjs.com/package/@alessiofrittoli/url-utils#urlinput) type for more info. |\n| `size` | `number` | The Media Artwork image size. |\n| | | Common values are: `96`, `128`, `192`, `256`, `384`, `512`. |\n| `type` | `MIMEType` | The Media Artwork image MIME type. |\n\n\n\n---\n\n###### `Media`\n\nDefines the media.\n\nExtends the global [`MediaMetadata`](https://developer.mozilla.org/en-US/docs/Web/API/MediaMetadata) interface.\n\n\n\nProperties\n\n| Property | Type | Description |\n| --------- | ---------------- | --------------------------------------------------------------------------------------------------- |\n| `src` | `UrlInput` | The media URL. |\n| | | See [`UrlInput`](https://npmjs.com/package/@alessiofrittoli/url-utils#urlinput) type for more info. |\n| `type` | `MIMEType` | The media MIME type. |\n| `title` | `string` | The title of the media. |\n| `artwork` | `MediaArtWork[]` | The media artwork. |\n| | | See [`MediaArtWork`](#mediaartwork) type for more info. |\n| `artist` | `string` | The artist of the media. |\n| `album` | `string` | The album of the media. |\n\n\n\n---\n\n###### `UpdateMediaMetadataAndPositionOptions`\n\nDefines the MediaSession update options.\n\n\n\nProperties\n\n| Property | Type | Description |\n| -------- | -------------------- | ----------------------- |\n| `media` | `HTMLMediaElement` | The HTMLMediaElement. |\n| `data` | `Omit` | The playing media data. |\n\n\n\n---\n\n##### `updatePositionState()`\n\nUpdate `MediaSession` position state.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------------ | --------------------- |\n| `media` | `HTMLMediaElement` | The HTMLMediaElement. |\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { updatePositionState } from \"@alessiofrittoli/media-utils\";\n\nnavigator.mediaSession.setActionHandler(\"seekto\", (details) => {\n if (typeof details.seekTime === \"undefined\") return;\n\n media.currentTime = details.seekTime;\n\n updatePositionState(media);\n});\n```\n\n\n\n---\n\n##### `updateMediaMetadata()`\n\nUpdate `MediaSession` metadata.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | -------------------- | ----------------------- |\n| `data` | `Omit` | The playing media data. |\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { updateMediaMetadata } from \"@alessiofrittoli/media-utils\";\n\nmedia.play().then(() => {\n updateMediaMetadata({\n type: \"audio/mpeg\",\n title: \"Song name\",\n album: \"Album name\",\n artist: \"Artist name\",\n artwork: [\n {\n src: { pathname: \"/path-to-image-96.png\" },\n size: 96,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-128.png\" },\n size: 128,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-192.png\" },\n size: 192,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-256.png\" },\n size: 256,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-384.png\" },\n size: 384,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-512.png\" },\n size: 512,\n type: \"image/png\",\n },\n ],\n });\n});\n```\n\n\n\n---\n\n##### `updateMediaMetadataAndPosition()`\n\nUpdate `MediaSession` metadata and position state.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `options` | `UpdateMediaMetadataAndPositionOptions` | An object defining `media` HTMLMediaElement and associated data. |\n| | | See [`UpdateMediaMetadataAndPositionOptions`](#updatemediametadataandpositionoptions) for more info. |\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { updateMediaMetadataAndPosition } from \"@alessiofrittoli/media-utils\";\n\nmedia.play().then(() => {\n updateMediaMetadataAndPosition({\n media,\n data: {\n type: \"audio/mpeg\",\n title: \"Song name\",\n album: \"Album name\",\n artist: \"Artist name\",\n artwork: [\n {\n src: { pathname: \"/path-to-image-96.png\" },\n size: 96,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-128.png\" },\n size: 128,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-192.png\" },\n size: 192,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-256.png\" },\n size: 256,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-384.png\" },\n size: 384,\n type: \"image/png\",\n },\n {\n src: { pathname: \"/path-to-image-512.png\" },\n size: 512,\n type: \"image/png\",\n },\n ],\n },\n });\n});\n```\n\n\n\n---\n\n#### `AudioEngine`\n\nManages volume manipulation for HTML media elements.\n\nProvides methods for fading volume with customizable tweening, and utilities for converting\nbetween normalized volume values (0.0-1.0) and linear gain values using decibel-based calculations\nthat better match human perception of audio loudness.\n\n- Refer to the [Audio Engine Manager](#audio-engine-manager) section to understand how instance caching prevents redundant `AudioEngine` instantiation.\n\n##### AudioEngine Types\n\n###### `TickHandler`\n\nCallback executed on each interpolation tick.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | -------- | ------------------------------- |\n| `value` | `number` | The current interpolated value. |\n\n\n\n---\n\n###### `FadeVolumeOptions`\n\n\n\nProperties\n\n| Property | Type | Default | Description |\n| ---------- | ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------- |\n| `to` | `number` | - | Defines the final volume to set [0-1]. |\n| `duration` | `number` | `200` | (Optional) Duration of the tween in milliseconds. |\n| `onTick` | `TickHandler` | - | Callback executed on each interpolation tick. |\n| | | | See [`TickHandler`](#tickhandler) types for more info. |\n| `onEnd` | `TickHandler` | - | (Optional) Callback executed when the interpolation completes. |\n| | | | See [`TickHandler`](#tickhandler) types for more info. |\n| `easing` | `EasingFn` | `Easing.linear` | (Optional) Easing function used to transform the linear time progression. |\n| | | | See [`EasingFn`](https://github.com/alessiofrittoli/math-utils/blob/master/docs/easing/README.md#easingfn) types for more info. |\n| `Hz` | `number` | `120` | (Optional) Custom tick rate in Hz. |\n\n\n\n---\n\n##### Methods\n\n###### `AudioEngine.fade()`\n\nFade media volume.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------------- | ------------------------------------------------------------ |\n| `options` | `FadeVolumeOptions` | An object defining customization and callbacks. |\n| | | See [`FadeVolumeOptions`](#fadevolumeoptions) for more info. |\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { AudioEngine } from '@alessiofrittoli/media-utils/audio'\n\nconst audio = new Audio( ... )\nconst engine = new AudioEngine( audio )\n\naudio.volume = 0\naudio.play()\n .then( () => {\n // Fade volume to 0.5 over 2 seconds\n engine.fade( {\n to : 1,\n duration : 2000,\n } )\n } )\n```\n\n\n\n---\n\n##### Static methods\n\n###### `AudioEngine.VolumeToGain()`\n\nConverts a volume value (0.0 to 1.0) to a linear gain value.\n\nThe returned value will better match the human perceived volume.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | -------- | ----------------------------------------------------------------------------- |\n| `volume` | `number` | The volume value, where 0 represents silence and 1 represents maximum volume. |\n\n\n\n---\n\n\n\nReturns\n\nType: `number`.\n\nThe corresponding linear gain value, or 0 if the gain is effectively inaudible.\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { AudioEngine } from '@alessiofrittoli/media-utils/audio'\n\nconst audio = new Audio( ... )\nconst engine = new AudioEngine( audio )\n\naudio.volume = 0\naudio.play()\n .then( () => {\n engine.fade( {\n to: AudioEngine.VolumeToGain( 0.5 ),\n onEnd() {\n console.log( audio.volume ) // Outputs: `0.03162277660168379`\n },\n } )\n } )\n```\n\n\n\n---\n\n###### `AudioEngine.GainToVolume()`\n\nConverts a linear gain value to a normalized volume value between 0 and 1.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | -------- | --------------------------------- |\n| `gain` | `number` | The linear gain value to convert. |\n\n\n\n---\n\n\n\nReturns\n\nType: `number`.\n\nThe normalized volume value in the range [0, 1].\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { AudioEngine } from '@alessiofrittoli/media-utils/audio'\n\nconst audio = new Audio( ... )\nconst engine = new AudioEngine( audio )\n\naudio.volume = 0\naudio.play()\n .then( () => {\n engine.fade( {\n to: AudioEngine.VolumeToGain( 0.5 ),\n onEnd() {\n console.log( audio.volume ) // Outputs: `0.03162277660168379`\n console.log( AudioEngine.GainToVolume( audio.volume ) ) // Outputs: `0.5`\n },\n } )\n } )\n```\n\n\n\n---\n\n###### `AudioEngine.normalize()`\n\nConditionally normalize volume using [`AudioEngine.VolumeToGain`](#audioenginevolumetogain).\n\nThis method acts as a wrapper and has the same API of [`AudioEngine.VolumeToGain()`](#audioenginevolumetogain) but it accepts a boolean value\nas second argument that allows you to quickly opt-in/opt-out based on an incoming variable,\nthus there is no need to call `AudioEngine.VolumeToGain()` conditionally.\n\n\n\nExamples\n\n```ts\nimport { AudioEngine } from '@alessiofrittoli/media-utils/audio'\n\n// `normalizeAudio` may come from global settings\nconst audio = new Audio( ... )\nconst engine = new AudioEngine( audio )\n\naudio.volume = 0\naudio.play()\n .then( () => {\n engine.fade( {\n to: AudioEngine.normalize( 0.5, normalizeAudio ),\n onEnd() {\n console.log( audio.volume ) // Outputs: `0.03162277660168379` if `normalizeAudio` is set to `true`, 0.5 otherwise.\n },\n } )\n } )\n```\n\n\n\n---\n\n###### `AudioEngine.denormalize()`\n\nConditionally denormalize volume using [`AudioEngine.GainToVolume`](#audioenginegaintovolume).\n\nThis method acts as a wrapper and has the same API of [`AudioEngine.GainToVolume()`](#audioenginegaintovolume) but it accepts a boolean value\nas second argument that allows you to quickly opt-in/opt-out based on an incoming variable,\nthus there is no need to call `AudioEngine.GainToVolume()` conditionally.\n\n\n\nExamples\n\n```ts\nimport { AudioEngine } from '@alessiofrittoli/media-utils/audio'\n\n// `normalizeAudio` may come from global settings\nconst audio = new Audio( ... )\nconst engine = new AudioEngine( audio )\n\naudio.volume = 0\naudio.play()\n .then( () => {\n engine.fade( {\n to: AudioEngine.normalize( 0.5, normalizeAudio ),\n onEnd() {\n console.log(\n AudioEngine.denormalize( audio.volume, normalizeAudio )\n )\n },\n } )\n } )\n```\n\n\n\n---\n\n##### Audio Engine Manager\n\nThe Audio Engine Manager is responsible for maintaining a one-to-one association between an `HTMLMediaElement` and its corresponding `AudioEngine` instance.\nIts primary goal is to prevent unnecessary re-creation of `AudioEngine` objects when interacting with the same media element.\n\nWhen working with audio processing APIs, repeatedly instantiating `AudioEngine` for the same HTMLMediaElement would:\n\n- Introduce unnecessary computational overhead.\n- Potentially duplicate internal state.\n- Increase memory usage.\n- Lead to inconsistent behavior.\n\nThe manager ensures that each media element has exactly one `AudioEngine` instance.\n\n###### `getEngine()`\n\nGet the `AudioEngine` associated with the given `media`. If none exists, it lazily creates a new instance.\n\n\n\nParameters\n\n| Parameter | type | Decription |\n| --------- | ------------------ | --------------------- |\n| `media` | `HTMLMediaElement` | The HTMLMediaElement. |\n\n\n\n---\n\n\n\nReturns\n\nType: `AudioEngine`.\n\nThe `AudioEngine` associated with the given `media` or a new `AudioEngine` instance if none exists.\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { getEngine } from \"@alessiofrittoli/media-utils/audio\";\n\nconst mute = (media: HTMLMediaElement) => {\n getEngine(media).fade({ to: 0 });\n};\n\nconst unmute = (media: HTMLMediaElement) => {\n getEngine(media).fade({ to: 1 });\n};\n```\n\n\n\n---\n\n###### `destroyEngine()`\n\nProactively delete the `AudioEngine` associated with the given `media` to free resources.\n\n\n\nParameters\n\n| Parameter | type | Decription |\n| --------- | ------------------ | --------------------- |\n| `media` | `HTMLMediaElement` | The HTMLMediaElement. |\n\n\n\n---\n\n\n\nReturns\n\nType: `boolean`.\n\n- `true` if the element was successfully removed.\n- `false` if no engine was registered.\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { getEngine, destroyEngine } from \"@alessiofrittoli/media-utils/audio\";\n\nconst stop = (media: HTMLMediaElement) => {\n getEngine(media).fade({\n to: 0,\n onEnd() {\n media.pause();\n destroyEngine(media);\n },\n });\n};\n```\n\n\n\n---\n\n##### Audio Utilities\n\n###### `fadeVolume()`\n\nFade media volume.\n\nThis utility function acts as a wrapper handling [`AudioEngine`](#audioengine) instances for you using the [Audio Engine Manager](#audio-engine-manager).\n\n\n\nParameters\n\n| Parameter | type | Decription |\n| --------- | ------------------- | ------------------------------------------------------------ |\n| `media` | `HTMLMediaElement` | The HTMLMediaElement. |\n| `options` | `FadeVolumeOptions` | An object defining customization and callbacks. |\n| | | See [`FadeVolumeOptions`](#fadevolumeoptions) for more info. |\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { fadeVolume } from \"@alessiofrittoli/media-utils/audio\";\n\nconst play = (media: HTMLMediaElement) => {\n media.volume = 0;\n media.play().then(() => {\n fadeVolume(media, { to: 1 });\n });\n};\n```\n\n\n\n---\n\n#### Media Playback\n\n#### Media Playback types\n\n##### `PlayMediaOptions`\n\nAn object defining play options and callbacks.\n\nIt extends [`UpdateMediaMetadataAndPositionOptions`](#updatemediametadataandpositionoptions) and [`FadeVolumeOptions`](#fadevolumeoptions) interfaces and adds/overrides the following properties.\n\n\n\nProperties\n\n| Property | Type | Default | Description |\n| --------- | ------------------------------- | ------- | -------------------------------------------------------------------------------- |\n| `volume` | `number` | - | Defines the final volume to set [0-1]. |\n| | | | - overrides `FadeVolumeOptions['to']` |\n| `fade` | `number` | `200` | (Optional) A custom volume fade duration in milliseconds. |\n| | | | - overrides `FadeVolumeOptions['duration']` |\n| `onError` | `( error: MediaError ) => void` | - | (Optional) A custom callback executed when an error occurs when playing a media. |\n\n\n\n---\n\n##### `PauseMediaOptions`\n\nAn object defining pause options and callbacks.\n\nIt extends [`PlayMediaOptions`](#playmediaoptions) and omits unnecessary properties.\n\n---\n\n#### `playMedia()`\n\nPlay the given media.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------------ | ---------------------------------------------------------- |\n| `options` | `PlayMediaOptions` | An object defining play options and callbacks. |\n| | | See [`PlayMediaOptions`](#playmediaoptions) for more info. |\n\n\n\n---\n\n\n\nReturns\n\nType: `Promise`\n\nA new `Promise` which resolves once `media.play()` promise is resolved.\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { playMedia } from \"@alessiofrittoli/media-utils\";\n\nconst media = new Audio( ... )\n\nplay.addEventListener(\"click\", () => {\n\n playMedia( {\n media,\n volume: 1,\n fade: 800,\n data: {\n type: 'audio/mpeg',\n title: 'Media title',\n },\n onError( error ) {\n switch ( error.code ) {\n case MediaError.MEDIA_ERR_ABORTED:\n console.error( 'The fetching of the associated resource was aborted by the user\\'s request.' )\n break\n case MediaError.MEDIA_ERR_NETWORK:\n console.error( 'Some kind of network error occurred which prevented the media from being successfully fetched, despite having previously been available.' )\n break\n case MediaError.MEDIA_ERR_DECODE:\n console.error( 'Despite having previously been determined to be usable, an error occurred while trying to decode the media resource, resulting in an error.' )\n break\n case MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED:\n console.error( 'The associated resource or media provider object (such as a MediaStream) has been found to be unsuitable.' )\n break\n default:\n console.error( 'Unknow error.' )\n }\n },\n } )\n\n});\n```\n\n\n\n---\n\n#### `pauseMedia()`\n\nPause the given media.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------------- | --------------------------------------------------------------------------- |\n| `options` | `PauseMediaOptions` | An object defining pause options and callbacks. |\n| | | See [`PauseMediaOptions`](#pausemediaoptions) for more info. for more info. |\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { pauseMedia } from \"@alessiofrittoli/media-utils\";\n\nconst media = new Audio( ... )\n\npause.addEventListener(\"click\", () => {\n\n pauseMedia( { media, fade: 800 } )\n\n});\n```\n\n\n\n---\n\n#### Image Video Stream\n\n##### Types\n\n###### `CreateImageVideoStreamOptions` interface\n\nOptions for rendering an image into a video stream.\n\nIt optionally accepts a previously created `HTMLVideoElement` where image will get streamed into.\n\n\n\nProperties\n\n- Extends [`RenderOptions`](#renderoptions-interface) interface.\n\n| Property | Type | Default | Description |\n| -------- | ------------------------ | ------- | ---------------------------------------------------------------------------------------- |\n| `media` | `Blob\\|HTMLImageElement` | - | The image source to render. It can be either a `Blob` or a preloaded `HTMLImageElement`. |\n\n\n\n---\n\n###### `RenderOptions` interface\n\nRendering options.\n\n\n\nProperties\n\n| Property | Type | Default | Description |\n| ------------- | ------------------------ | --------- | --------------------------------------------------------------------------------------------------- |\n| `media` | `Blob\\|HTMLImageElement` | - | (Optional) The image source to render. It can be either a `Blob` or a preloaded `HTMLImageElement`. |\n| `video` | `HTMLVideoElement` | - | (Optional) A previously created `HTMLVideoElement` where image get streamed into. |\n| `aspectRatio` | `number` | - | (Optional) Target aspect ratio (width / height) of the rendering area. |\n| | | | If omitted, the original media aspect ratio is preserved. |\n| `fit` | `'contain'\\|'cover'` | `contain` | (Optional) Defines how the media should fit inside the rendering area. |\n| | | | - `contain` (default) behaves like `object-fit: contain` |\n| | | | - `cover` behaves like `object-fit: cover` |\n| | | | Only applies when `aspectRatio` is specified. |\n\n\n\n---\n\n###### `RenderResult` interface\n\nThe rendering result.\n\n\n\nProperties\n\n| Property | Type | Description |\n| -------- | ------------------ | ----------------------------------------------------- |\n| `video` | `HTMLVideoElement` | The `HTMLVideoElement` where image get streamed into. |\n\n\n\n---\n\n###### `RenderHandler` type\n\nRender a new image to the video stream.\n\n```ts\ntype RenderHandler = (options?: RenderOptions) => Promise;\n```\n\n---\n\n###### `DestroyHandler` type\n\nStop stream tracks and release allocated resources.\n\n```ts\ntype DestroyHandler = () => void;\n```\n\n---\n\n###### `CreateImageVideoStream` interface\n\nDefines the returned result of rendering an image into a video.\n\n\n\nProperties\n\n- Extends [`RenderResult`](#renderresult-interface) interface.\n\n| Property | Type | Description |\n| --------- | ---------------- | ---------------------------------------------------- |\n| `render` | `RenderHandler` | Render a new image to the video stream. |\n| | | - See [`RenderHandler` type](#renderhandler-type). |\n| `destroy` | `DestroyHandler` | Stop stream tracks and release allocated resources. |\n| | | - See [`DestroyHandler` type](#destroyhandler-type). |\n\n\n\n---\n\n##### `createImageVideoStream`\n\nRender an image into a video stream.\n\nIf the provided media (HTMLImageElement) fails to load, a 1x1 black frame is rendered instead and the promise does not reject.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------------------------- | -------------------------------------------------------------------------------------------- |\n| `options` | `CreateImageVideoStreamOptions` | Rendering options. |\n| | | - See [`CreateImageVideoStreamOptions`](#createimagevideostreamoptions-interface) interface. |\n\n\n\n---\n\n\n\nReturns\n\nType: `Promise`\n\nA new Promise that resolves the allocated rendering resources.\n\n\n\n---\n\n\n\nExamples\n\n###### Fetch and render image Blob\n\n```ts\nimport { fetch } from \"@alessiofrittoli/fetcher\";\nimport {\n getFallbackImage,\n createImageVideoStream,\n} from \"@alessiofrittoli/media-utils\";\n\nconst createImageStream = async () => {\n const { data: media, error } = await fetch(\"/path-to/image.png\", {\n responseType: \"blob\",\n });\n\n if (error) {\n return createImageVideoStream({ media: getFallbackImage() });\n }\n\n return createImageVideoStream({ media });\n};\n```\n\n---\n\n###### Custom aspect ratio\n\n```ts\nimport { createImageVideoStream } from \"@alessiofrittoli/media-utils\";\n\nconst createImageStream = () => {\n const media = document.createElement(\"img\");\n media.src = \"/path-to/image.png\";\n\n return createImageVideoStream({\n media,\n aspectRatio: 16 / 9,\n fit: \"cover\", // or 'contain'\n });\n};\n```\n\n---\n\n###### Update streamed content\n\n```ts\nimport { createImageVideoStream } from \"@alessiofrittoli/media-utils\";\n\nconst createImageStream = async () => {\n const media = document.createElement(\"img\");\n media.src = \"/path-to/image.png\";\n\n const { video, render } = await createImageVideoStream({\n media,\n aspectRatio: 16 / 9,\n fit: \"cover\", // or 'contain'\n });\n\n // update streamed content after 5 seconds\n setTimeout(() => {\n media.src = \"/path-to/image-2.png\";\n\n await render({ aspectRatio: 1 });\n }, 5000);\n\n return video;\n};\n```\n\n---\n\n###### Using a previously created video\n\n```ts\nimport { createImageVideoStream } from \"@alessiofrittoli/media-utils\";\n\nconst createImageStream = async () => {\n const video = document.createElement(\"video\");\n video.src = \"/path-to/video.mp4\";\n\n const media = document.createElement(\"img\");\n media.src = \"/path-to/image.png\";\n\n // replace original video content with streamed image\n await createImageVideoStream({\n media,\n video,\n aspectRatio: 16 / 9,\n fit: \"cover\", // or 'contain'\n });\n\n return video;\n};\n```\n\n---\n\n###### Free allocated resources\n\n```ts\nimport { createImageVideoStream } from \"@alessiofrittoli/media-utils\";\n\nconst createImageStream = async () => {\n const media = document.createElement(\"img\");\n media.src = \"/path-to/image.png\";\n\n // replace original video content with streamed image\n const { video, destroy } = await createImageVideoStream({\n media,\n aspectRatio: 16 / 9,\n fit: \"cover\", // or 'contain'\n });\n\n // free allocated resources after 5 seconds\n setTimeout(() => {\n destroy();\n }, 5000);\n\n return video;\n};\n```\n\n\n\n---\n\n#### Media Artwork Picture-in-Picture\n\n##### Types\n\n###### `OpenPictureInPictureCommonOptions` interface\n\nDefines common configuration options for opening the media in Picture-in-Picture mode.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------ | -------------------------------------------------------------------------- |\n| `onQuit` | `() => void` | (Optional) A callback to execute when Picture-in-Picture window is closed. |\n\n\n\n---\n\n###### `OpenImagePictureInPictureOptions` interface\n\nDefines configuration options for opening the image in Picture-in-Picture mode.\n\n\n\nParameters\n\n- Extends [`OpenPictureInPictureCommonOptions`](#openpictureinpicturecommonoptions-interface) interface.\n- Extends [`CreateImageVideoStreamOptions`](#createimagevideostreamoptions-interface) interface.\n- Partially extends [`CreateImageVideoStream`](#createimagevideostream-interface) interface.\n\n| Parameter | Type | Description |\n| --------- | ---------------------------------------------------- | --------------------------------------------------- |\n| `media` | `CreateImageVideoStreamOptions[ 'media' ]\\|UrlInput` | The media to render in a Picture-in-Picture window. |\n\n\n\n---\n\n###### `OpenImagePictureInPicture` type\n\nDefines the returned result of opening a rendered image into a video Picture-in-Picture window.\n\n- Alias for [`CreateImageVideoStream`](#createimagevideostream-interface) interface\n\n---\n\n###### `OpenVideoArtworkPictureInPictureOptions` interface\n\nDefines configuration options for opening the video in Picture-in-Picture window.\n\n\n\nParameters\n\n- Extends [`OpenPictureInPictureCommonOptions`](#openpictureinpicturecommonoptions-interface) interface.\n- Partially extends [`OpenVideoArtworkPictureInPicture`](#openvideoartworkpictureinpictureoptions-interface) interface.\n\n| Parameter | Type | Description |\n| --------- | ---------------------------- | ------------------------------------------------- |\n| `media` | `HTMLVideoElement\\|UrlInput` | The media to open in a Picture-in-Picture window. |\n\n\n\n---\n\n###### `OpenVideoArtworkPictureInPicture` interface\n\nDefines the returned result of opening a video into a Picture-in-Picture window.\n\n\n\nProperties\n\n| Property | Type | Description |\n| -------- | ------------------ | --------------------------------------------- |\n| `video` | `HTMLVideoElement` | The `HTMLVideoElement` in Picture-in-Picture. |\n\n\n\n---\n\n###### `OpenArtworkPictureInPictureOptions` interface\n\nDefines configuration options for opening media artwork in Picture-in-Picture window.\n\n\n\nParameters\n\n- Extends [`OpenImagePictureInPictureOptions`](#openimagepictureinpictureoptions-interface) interface.\n- Extends [`OpenVideoArtworkPictureInPictureOptions`](#openvideoartworkpictureinpictureoptions-interface) interface.\n\n| Parameter | Type | Description |\n| --------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |\n| `media` | `CreateImageVideoStreamOptions['media']\\| HTMLVideoElement\\|MediaArtWork` | The media to open in a Picture-in-Picture window. |\n| | | - See [`CreateImageVideoStreamOptions`](#createimagevideostream-interface) interface. |\n| | | - See [`MediaArtWork`](#mediaartwork) interface. |\n\n\n\n---\n\n###### `OpenArtworkPictureInPicture` interface\n\nDefines the returned result of opening a media artwork into a Picture-in-Picture window.\n\nIt could be [`OpenImagePictureInPicture`](#openimagepictureinpicture-type) or [`OpenVideoArtworkPictureInPicture`](#openvideoartworkpictureinpicture-interface).\n\n---\n\n##### `isPictureInPictureSupported`\n\nChecks if the Picture-in-Picture API is supported by the current browser.\n\n---\n\n##### `requiresPictureInPictureAPI`\n\nValidates that the Picture-in-Picture API is supported by the current browser.\n\n- Throws a new `Exception` with code `ErrorCode.PIP_NOT_SUPPORTED` if the Picture-in-Picture API is not supported.\n\n---\n\n##### `openImagePictureInPicture`\n\nOpens an image in Picture-in-Picture window.\n\nOnce Picture-in-Picture get closed by the user, allocated resources are automatically freed.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- |\n| `options` | `OpenImagePictureInPictureOptions` | Configuration options for opening the image in PiP window. |\n| | | - See [`OpenImagePictureInPictureOptions`](#openimagepictureinpictureoptions-interface) interface. |\n\n\n\n---\n\n\n\nReturns\n\nType: `Promise`\n\nA new Promise that resolves to the Picture-in-Picture result containing the video element and destroy function.\n\n- See [`OpenImagePictureInPicture`](#openimagepictureinpicture-type) for more info.\n\n\n\n---\n\n\n\nExamples\n\n###### Simple usage\n\n```ts\nimport {\n ErrorCode,\n openImagePictureInPicture,\n} from \"@alessiofrittoli/media-utils\";\n\ntry {\n navigator.mediaSession.setActionHandler(\"enterpictureinpicture\", async () => {\n try {\n await openImagePictureInPicture({\n media: { pathname: \"path/to/image.png\" },\n aspectRatio: 1,\n fit: \"cover\",\n onQuit: () => console.log(\"Picture-in-Picture closed\"),\n });\n } catch (_err) {\n const err = _err as Error;\n\n const error = Exception.isException(err)\n ? err\n : new Exception(err.message, {\n code: ErrorCode.UNKNOWN,\n name: err.name,\n cause: err,\n });\n switch (error.code) {\n case ErrorCode.PIP_NOT_SUPPORTED:\n alert(\"Picture-In-Picture is not supported by the current browser.\");\n break;\n case ErrorCode.RENDERING_CONTEXT_UNAVAILABLE:\n alert(\"Couldn't render image in Picture-in-Picture.\");\n break;\n default:\n console.error(error);\n }\n }\n });\n} catch (error) {\n console.warn(\n 'Warning! The \"enterpictureinpicture\" media session action is not supported.',\n error,\n );\n}\n```\n\n---\n\n###### Update image Picture-in-Picture content\n\n```ts\nimport {\n openImagePictureInPicture,\n type OpenImagePictureInPicture,\n} from \"@alessiofrittoli/media-utils\";\n\nlet resources: OpenImagePictureInPicture;\n\nnavigator.mediaSession.setActionHandler(\"enterpictureinpicture\", async () => {\n resources = await openImagePictureInPicture({\n media: { pathname: \"/path/to/image.png\" },\n });\n});\n\nnavigator.mediaSession.setActionHandler(\"nexttrack\", async () => {\n resources = await openImagePictureInPicture({\n media: { pathname: \"/path/to/image.png\" },\n ...resources,\n });\n});\n```\n\n\n\n---\n\n##### `openVideoArtworkPictureInPicture`\n\nOpens a video artwork element in Picture-in-Picture window.\n\nThis function is intended for rendering a short song artwork video.\nThis is not suitable if your're looking for a proper video Picture-in-Picture since it simple as calling `video.requestPictureInPicture()`.\n\nSupports both `HTMLVideoElement` instances and URL inputs. When a URL is provided, a video element is created and the URL is set as its source.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |\n| `options` | `OpenVideoArtworkPictureInPictureOptions` | Configuration options for opening the video in Picture-in-Picture. |\n| | | - See [`OpenVideoArtworkPictureInPictureOptions`](#openvideoartworkpictureinpictureoptions-interface) interface. |\n\n\n\n---\n\n\n\nReturns\n\nType: `Promise`\n\nA new Promise that resolves with an object containing the video element displayed in Picture-in-Picture mode.\n\n- See [`OpenVideoArtworkPictureInPicture`](#openvideoartworkpictureinpicture-interface) for more info.\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { openVideoArtworkPictureInPicture } from \"@alessiofrittoli/media-utils\";\n\n// With a URL\nconst { video } = await openVideoArtworkPictureInPicture({\n media: \"/song-artwork-video.mp4\",\n onQuit: () => console.log(\"Picture-in-Picture closed\"),\n});\n\n// With an HTMLVideoElement\nconst media = document.querySelector(\"video\");\nmedia.src = \"/song-artwork-video.mp4\";\n\nconst { video } = await openVideoArtworkPictureInPicture({ media });\n```\n\n\n\n---\n\n##### `openArtworkPictureInPicture`\n\nOpens the given media in Picture-in-Picture window.\n\nIt easly handles images and videos rendering using [`openImagePictureInPicture`](#openimagepictureinpicture) or [`openVideoArtworkPictureInPicture`](#openvideoartworkpictureinpicture).\n\nOnce Picture-in-Picture get closed by the user, allocated resources are automatically freed.\n\n\n\nParameters\n\n| Parameter | Type | Description |\n| --------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |\n| `options` | `OpenArtworkPictureInPictureOptions` | Configuration options for opening the media in Picture-in-Picture window. |\n| | | - See [`OpenArtworkPictureInPictureOptions`](#openartworkpictureinpictureoptions-interface) interface. |\n\n\n\n---\n\n\n\nReturns\n\nType: `Promise`\n\nA new Promise that resolves to the Picture-in-Picture result.\n\n- See [`OpenArtworkPictureInPicture`](#openartworkpictureinpicture-interface).\n\n\n\n---\n\n\n\nExamples\n\n###### Simple usage\n\n```ts\nimport { openArtworkPictureInPicture } from \"@alessiofrittoli/media-utils\";\n\nconst result = await openArtworkPictureInPicture({\n media: {\n type: \"image/png\",\n src: \"/path/to/image.png\",\n },\n aspectRatio: 1,\n fit: \"cover\",\n});\n\n// update\nawait openArtworkPictureInPicture({\n media: {\n type: \"video/mp4\",\n src: \"/path/to/video.mp4\",\n },\n ...result,\n});\n```\n\n---\n\n###### Using media session image\n\n```ts\nimport {\n openArtworkPictureInPicture,\n updateMediaMetadata,\n type MediaSessionMetadata,\n} from \"@alessiofrittoli/media-utils\";\n\nconst data: MediaSessionMetadata = {\n title: \"Test Song\",\n artist: \"Test Artist\",\n album: \"Test Album\",\n artwork: [\n { src: \"/path/to/song-artwork.png\", sizes: 128, type: \"image/png\" },\n ],\n};\n\nupdateMediaMetadata(data);\n\nawait openArtworkPictureInPicture();\n```\n\n---\n\n###### Handling errors\n\n```ts\nimport {\n ErrorCode,\n openArtworkPictureInPicture,\n} from \"@alessiofrittoli/media-utils\";\n\ntry {\n await openArtworkPictureInPicture({ ... });\n} catch (_err) {\n const err = _err as Error;\n\n const error = Exception.isException(err)\n ? err\n : new Exception(err.message, {\n code: ErrorCode.UNKNOWN,\n name: err.name,\n cause: err,\n });\n switch (error.code) {\n case ErrorCode.PIP_NOT_SUPPORTED:\n alert(\"Picture-In-Picture is not supported by the current browser.\");\n break;\n case ErrorCode.RENDERING_CONTEXT_UNAVAILABLE:\n alert(\"Couldn't render image in Picture-in-Picture.\");\n break;\n default:\n console.error(error);\n }\n}\n```\n\n\n\n---\n\n#### Utilities\n\n##### `formatMediaTiming()`\n\nFormats a time value in seconds into a human-readable media timing string (M:SS or H:MM:SS).\n\n\n\nParameters\n\n| Parameter | Type | Default | Description |\n| ----------- | --------- | ------- | ------------------------------------------------------------ |\n| `time` | `number` | - | The time value in seconds to format. |\n| `showHours` | `boolean` | `false` | (Optional) Whether to include hours in the formatted output. |\n\n\n\n---\n\n\n\nReturns\n\nType: `string`\n\nA formatted time string in the format \"M:SS\" or \"H:MM:SS\" if `showHours` is `true`.\nIf the time is 0 or invalid, returns \"0:00\".\n\n\n\n---\n\n\n\nExamples\n\n```ts\nimport { formatMediaTiming } from \"@alessiofrittoli/media-utils\";\n\nconsole.log(formatMediaTiming(45)); // Outputs: \"0:45\"\nconsole.log(formatMediaTiming(90)); // Outputs: \"1:30\"\nconsole.log(formatMediaTiming(125)); // Outputs: \"2:05\"\n\nconsole.log(formatMediaTiming(3661, true)); // Outputs: \"1:01:01\"\n\nconsole.log(formatMediaTiming(0)); // Outputs: \"0:00\"\nconsole.log(formatMediaTiming(-NaN)); // Outputs: \"0:00\"\nconsole.log(formatMediaTiming(NaN)); // Outputs: \"0:00\"\nconsole.log(formatMediaTiming(-Infinity)); // Outputs: \"0:00\"\nconsole.log(formatMediaTiming(Infinity)); // Outputs: \"0:00\"\n\nconsole.log(formatMediaTiming(0, true)); // Outputs: \"0:00:00\"\nconsole.log(formatMediaTiming(-NaN, true)); // Outputs: \"0:00:00\"\nconsole.log(formatMediaTiming(NaN, true)); // Outputs: \"0:00:00\"\nconsole.log(formatMediaTiming(-Infinity, true)); // Outputs: \"0:00:00\"\nconsole.log(formatMediaTiming(Infinity, true)); // Outputs: \"0:00:00\"\n```\n\n\n\n---\n\n##### `getPreloadStrategy`\n\nDetermines the optimal preload strategy for media elements based on network conditions.\n\nIt returns a value that corresponds to the preload attribute used in HTML media elements like `
![\"Latest](\"https://img.shields.io/npm/v/@alessiofrittoli/media-utils\")
\n \n \n ![\"Test](\"https://coveralls.io/repos/github/alessiofrittoli/media-utils/badge.svg\"){kind=icon}
\n \n \n ![\"npm](\"https://img.shields.io/npm/dm/@alessiofrittoli/media-utils.svg\")
\n \n \n ![\"Dependencies](\"https://img.shields.io/librariesio/release/npm/@alessiofrittoli/media-utils\")
\n \n![\"Fund](\"https://img.shields.io/static/v1?label=Fund%20this%20package&message=%E2%9D%A4&logo=GitHub&color=%23DB61A2\")