<nftcdn-media-player>

This is a generic media viewer/player web component originally designed to display Cardano NFTs.

It supports the following media:

• Images
• Videos
• Audio files
• Web documents (HTML/Javascript/Css)
• PDF and plain text documents
• 3D models

And features:

• IPFS & Arweave URLs support (including gateway setting)
• Data URLs support (for example used in on-chain NFTs)
• Dynamic 3d model viewer loading only when needed
• Augmented reality for 3d models on mobile
• Follows the open-wc recommendation

Installation

npm i @nftcdn/media-player

Import

<script type="module">
  import '@nftcdn/media-player/nftcdn-media-player.js';
</script>

Or from esm.sh CDN without installation needed:

<script
  type="module"
  src="https://esm.sh/@nftcdn/media-player/nftcdn-media-player.js"
></script>

Usage

<nftcdn-media-player src="URL" type="MIME" name="NAME"></nftcdn-media-player>

Note that this component only works client-side. If your web framework uses SSR, check its documentation to import and use the component client-side only.

Attributes

Name	Requirement	Default	Description
src	mandatory	undefined	media URL
type	mandatory except for images	undefined	media/mime type
name	required for WCAG compliance	undefined	unique media name
ipfsgateway*	optional	https://ipfs.io	IPFS gateway
argateway*	optional	https://arweave.net	Arweave gateway
autoplay	optional	false	Play automatically. Supported by audio and video media. Implies muted when enabled for videos.
poster	optional	undefined	Optional poster for audio player (always displayed), 3d model and video player (during loading only).

* JavaScript properties are ipfsGateway and arGateway.

Supported media types

• image/*: <img> element browsers supported formats
• video/*: <video> element browsers supported formats
• audio/*: <audio> element browsers supported formats
• text/html: HTML/Javascript/Css versions supported by browsers
• application/pdf: using browsers native PDF viewer
• text/plain
• model/gltf+json, model/gltf-binary: versions supported by <model-viewer>

Underlying elements

The following underlying elements are used:

Type	Element
image	<img>
video	<video>
audio	<audio>
html	<iframe>
pdf	<object>
text	<object>
gltf	<model-viewer>

Events

The following events are supported by the <nftcdn-media-playezr> custom element when the underlying element used supports them:

Event	Description
load	Fires when the media has successfully loaded.
error	Fires when the media failed to load.

The original event from the underlying element is stored in the custom event detail property.

Example:

<nftcdn-media-player
  src="ipfs://bafybeidnye5ohaqjliyriep2huapmgfgzuo7zlaeqe3rv6dxvu5yb46igm"
  onload="console.log('loaded', event.detail)"
  onerror="console.log('error', event.detail)"
></nftcdn-media-player>

Styling and CSS

All the component parts can be styled using CSS ::part pseudo element:

Type	CSS Selector
image	nftcdn-media-player::part(img)
video	nftcdn-media-player::part(video)
audio	nftcdn-media-player::part(audio)
html	nftcdn-media-player::part(iframe)
pdf	nftcdn-media-player[type="application/pdf"]::part(object)
text	nftcdn-media-player[type="text/plain"]::part(object)
gltf	nftcdn-media-player::part(model-viewer)

For example, to change the way images fill the viewer container:

<style>
  nftcdn-media-player::part(img) {
    object-fit: fill;
  }
</style>

Demoing with Storybook

The Storybook is build on commits with GitHub Actions and published online to GitHub Pages:
https://nftcdn.github.io/media-player

To run a local instance of the Storybook, run

npm run storybook

To build a production version of Storybook, run

npm run storybook:build

Local Demo with web-dev-server

npm start

To run a local development server that serves the basic demo located in demo/index.html

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Testing with Web Test Runner

To execute a single test run:

npm run test

To run the tests in interactive watch mode run:

npm run test:watch

Pull requests must maintain 100% code coverage.