# IMS - Interactive Media Spots

[![npm version](https://badge.fury.io/js/interactive-media-spots.svg)](https://badge.fury.io/js/interactive-media-spots)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A lightweight collection of web components for interactive media visualization.

## Widgets

### ims-diff
An image comparison widget with slider control. Perfect for before/after visualizations.
```html
<ims-diff src-data="./diff-data.json"></ims-diff>
```

Configuration example:
```json
{
  "imsType": "diff",
  "version": "<VERSION>",
  "urlTemplate": "https://your-cdn.com/{UID}/{VARIANT}",
  "variants": ["320", "640", "860", "1024"],
  "cdnIdList": ["image1-id", "image2-id"],
  "filters": ["grayscale(100%)", "none"]
}
```

### ims-gallery
An interactive image gallery with touch support and fullscreen capabilities.

```html
<ims-gallery src-data="./gallery-data.json"></ims-gallery>
```

### ims-pano
A 360° panorama viewer with touch/mouse controls and zoom functionality.

```html
<ims-pano src-data="./pano-data.json"></ims-pano>
```

Configuration example:
```json
{
  "imsType": "pano",
  "version": "<VERSION>",
  "autoplay": false,
  "urlTemplate": "https://your-cdn.com/{UID}/{VARIANT}",
  "variants": ["640", "1024", "2048"],
  "cdnIdList": ["panorama-image-id"]
}
```

### ims-spinner
A 360° object viewer that supports sequence animation and interactive rotation.

```html
<ims-spinner src-data="./spinner-data.json"></ims-spinner>
```

Configuration example:
```json
{
  "imsType": "spinner",
  "version": "<VERSION>",
  "autoplay": true,
  "speed": 50,
  "showCover": true,
  "urlTemplate": "https://your-cdn.com/{UID}/{VARIANT}",
  "variants": ["320", "640", "1024"],
  "cdnIdList": ["frame1-id", "frame2-id", "..."]
}
```

### ims-video

A video player component with HLS support, captions, and customizable controls.

```html
<ims-video src-data="./spinner-data.json"></ims-video>
```

Configuration example:
```json
{
  "imsType": "video",
  "version": "<VERSION>",
  "autoplay": true,
  "coverUrl": "<COVER_IMAGE_URL>",
  "showCover": true,
  "hlsSrc": "<HLS_SOURCE_PATH>",
  "sources": "<SOURCE_DESCRIPTIONS>",
  "tracks": []
}
```


### ims-viewer
Universal component, that loads dependencies dynamically using CDN with the certain application version support.

```html
<ims-viewer src-data="./spinner-data.json"></ims-viewer>
```

## Installation & Usage

1. Include the necessary common dependencies via CDN or the files in your project structure:
```html
<script type="importmap">
  {
    "imports": {
      "@symbiotejs/symbiote": "https://cdn.jsdelivr.net/npm/@symbiotejs/symbiote@2.3.2/+esm",
      "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/+esm",
      "hls.js": "https://cdn.jsdelivr.net/npm/hls.js@1"
    }
  }
</script>
```

2. Connect the desired component from CDN or your own built files:
```html
<script type="module" src="https://cdn.jsdelivr.net/npm/interactive-media-spots@<VERSION>/wgt/viewer/index.js"></script>
```

3. (Optional) If you need to use the npm package (Data types, etc), install it:
```bash
npm install interactive-media-spots
```

4. Use the universal tag in your HTML:
```html
<ims-viewer src-data="./data.json"></ims-viewer>
```
In this case, the component will load dependencies dynamically using CDN with the certain application version support.

Or use the specific content tag. For example:
```html
<ims-spinner src-data="./data.json"></ims-spinner>
```

5. You can override the settings for each specific embed using HTML tag attributes.
```html
<ims-spinner src-data="./data.json" autoplay="false" speed="100"></ims-spinner>
```

## Common Features

All our widgets support:

- Adaptive content loading to optimize traffic and enhance page loading speed
- Adaptive DPI support
- Full-screen display mode
- Mobile device compatibility
- Alpha channel support for transparent backgrounds and background settings
- Easy universal integration using a custom HTML tag, without the need for JavaScript
- Seamless integration with all modern frameworks: React, Vue, Angular, etc.
- On-demand dynamic loading of necessary dependencies
- Simple and effective version management for widgets and required data
- Direct data encoding within images for use with specialized CDNs
- JSON for data and configuration transfer, both as static files and via API
- Ability to override settings for each specific embed using HTML tag attributes
- Flexible UI customization via standard CSS
- Compatibility with all popular modern frameworks
- Autogenerated URLs for used images to facilitate working with CDNs
- HLS (HTTP Live Streaming) support for video
- Watermarking for copyright protection (Coming soon!)
- Interactive hot spots for linking to other content, enabling the creation of more intricate and complex hypermedia stories (Coming soon!)
- Audio accompaniment (Coming soon!)
- 3D model viewer (Coming soon!)
- Lazy loading and advanced cross-widget memory management (Coming soon!)

> IMS is supported by all current versions of popular browsers.

## Articles and Demos

- [Concept details and live demo](https://rnd-pro.com/pulse/interactive-media-spots/)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT © [rnd-pro.com](https://rnd-pro.com)