npm package: @rethink-js/rt-video
Description: A lightweight JavaScript utility for highly customizable, lazy-loaded, and scroll-autoplaying video players using Plyr.
Author: Rethink JS
Latest version: 1.0.0

# rt-video

![Platform: Web](https://img.shields.io/badge/platform-web-000000)
![JavaScript](https://img.shields.io/badge/language-JavaScript-F7DF1E?logo=javascript)
[![npm version](https://img.shields.io/npm/v/%40rethink-js%2Frt-video.svg)](https://www.npmjs.com/package/@rethink-js/rt-video)
[![jsDelivr hits](https://data.jsdelivr.com/v1/package/npm/@rethink-js/rt-video/badge)](https://www.jsdelivr.com/package/npm/@rethink-js/rt-video)
[![License: MIT](https://img.shields.io/badge/License-MIT-FFD632.svg)](https://opensource.org/licenses/MIT)

`rt-video` is a lightweight JavaScript utility that creates highly customizable, lazy-loaded, and scroll-autoplaying video players using Plyr with:

- **Automatic dependency loading** (no manual installs for Plyr JS/CSS)
- **Zero-config defaults** (works out of the box)
- Attribute-driven configuration (supports both `data-rt-video-*` and `rt-video-*`)
- Support for **multiple instances** and responsive video URLs
- A clean global API under `window.RtVideo`
- Defensive fallbacks to avoid runtime crashes
- Seamless custom UI states (loading, active, thumbnails, and play buttons)

**Primary dependency (GitHub):** [https://github.com/sampotts/plyr](https://github.com/sampotts/plyr)

---

# Table of Contents

- [1. Installation](#1-installation)
  - [1.1 CDN (jsDelivr)](#11-cdn-jsdelivr)
  - [1.2 npm](#12-npm)
- [2. Quick Start](#2-quick-start)
- [3. Activation Rules](#3-activation-rules)
- [4. Configuration (HTML Attributes)](#4-configuration-html-attributes)
- [5. Multiple Instances](#5-multiple-instances)
- [6. Global API](#6-global-api)
- [7. Troubleshooting](#7-troubleshooting)
- [8. License](#8-license)

---

## 1. Installation

### 1.1 CDN (jsDelivr)

```html
<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-video@latest/dist/index.min.js"></script>
```

### 1.2 npm

```bash
npm install @rethink-js/rt-video
```

Then bundle or load `dist/index.min.js` as appropriate for your build setup.

---

## 2. Quick Start

Add the script to your page. Construct your video wrapper with the required `url`, `thumbnail`, and `button` attributes. `rt-video` will automatically load Plyr, hide the native UI behind your custom thumbnail, and handle the playback logic.

Example:

```html
<div rt-video rt-video-url="https://example.com/video.mp4">
  <img src="thumbnail.png" rt-video-thumbnail alt="Thumbnail" />
  <div rt-video-button>Play Video</div>
</div>

<script src="https://cdn.jsdelivr.net/npm/@rethink-js/rt-video@latest/dist/index.min.js"></script>
```

> **Note:** You can use either `data-rt-video-*` or `rt-video-*` for all attributes. They function identically.

---

## 3. Activation Rules

The library activates when **any** of the following are true:

- A wrapper element containing the `rt-video` (or `data-rt-video`) attribute is detected.
- Inside the wrapper, elements with `rt-video-thumbnail` and `rt-video-button` are present.

If the required wrapper and internal UI elements are found, the library will initialize the instance, inject necessary CSS, and fetch the Plyr dependency.

---

## 4. Configuration (HTML Attributes)

### Core Setup Attributes

| Attribute            | Description                                                                                                                                 |
| :------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `rt-video`           | **(Required)** <br> Marks the wrapper element to be initialized.                                                                            |
| `rt-video-url`       | **(Required)** Source URL (YouTube or MP4). <br> **Supports responsive breakpoints** (e.g., `desktop.mp4, 991:tablet.mp4, 479:mobile.mp4`). |
| `rt-video-thumbnail` | **(Required)** <br> Added to the image/div that acts as the custom video cover.                                                             |
| `rt-video-button`    | **(Required)** <br> Added to the element that acts as the custom play button.                                                               |

### Playback & Feature Attributes

| Attribute            | Description                                                                               | Default |
| :------------------- | :---------------------------------------------------------------------------------------- | :------ |
| `rt-video-autoplay`  | Enables scroll-based autoplay (auto-pauses when out of view). Forces `muted=true`.        | `false` |
| `rt-video-lazy`      | Defers initialization and Plyr loading until the wrapper is within 200px of the viewport. | `false` |
| `rt-video-muted`     | Mutes the video on load.                                                                  | `false` |
| `rt-video-loop`      | Loops the video indefinitely.                                                             | `false` |
| `rt-video-start`     | Start time in seconds. Safely injects media fragments (`#t=`) or YouTube API params.      | `null`  |
| `rt-video-end`       | End time in seconds. Loops or stops when this time is reached.                            | `null`  |
| `rt-video-volume`    | Initial volume level (e.g., `0.5` or `50`).                                               | `null`  |
| `rt-video-autopause` | Pauses this video automatically if another Plyr instance starts playing.                  | `false` |

### UI Customization

| Attribute           | Description                                                                                                             | Default                                                  |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------- |
| `rt-video-controls` | Comma-separated list of Plyr controls (e.g., `play, progress, mute, fullscreen`). Pass an empty string for no controls. | `play, progress, current-time, mute, volume, fullscreen` |
| `rt-video-color`    | Brand color for the Plyr UI. Accepts HEX codes or CSS variables (e.g., `#ff0000` or `--brand-color`).                   | `#131313`                                                |

---

## 5. Multiple Instances

`rt-video` natively supports multiple independent instances on the same page.

Each instance:

- Has its own configuration and breakpoints.
- Will lazy-load independently if `rt-video-lazy="true"` is applied.
- Can interact with other instances (e.g., pausing others if `rt-video-autopause` is active).

---

## 6. Global API

The package automatically initializes on `DOMContentLoaded`. However, if you are dynamically injecting video elements into the DOM after the initial page load (e.g., via AJAX or a modern framework router), you can manually re-trigger the initialization.

```js
window.RtVideo;
```

### Methods

| Method           | Description                                                                                                                                                  |
| :--------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RtVideo.init()` | Scans the DOM for uninitialized `[rt-video]` wrappers, loads dependencies if needed, and safely initializes new instances without duplicating existing ones. |

---

## 7. Troubleshooting

### Player is not initializing

- Ensure the wrapper has the `rt-video` attribute.
- Ensure both the `rt-video-thumbnail` and `rt-video-button` elements exist _inside_ the wrapper. The script skips initialization without them.

### Autoplay is not working

- Autoplay videos _must_ be muted to comply with modern browser policies. The script attempts to enforce this automatically, but ensure no conflicting scripts are overriding the volume.
- If using `rt-video-autoplay`, the video plays when 10% of the element is in view. Check for overlapping elements blocking the IntersectionObserver.

### Responsive URLs are loading the wrong video

- Ensure your `rt-video-url` string is formatted strictly as `default_url, max-width:override_url`.
- Example: `high-res.mp4, 991:medium-res.mp4, 479:low-res.mp4`.

---

## 8. License

MIT License

Package: `@rethink-js/rt-video` <br>
GitHub: [https://github.com/Rethink-JS/rt-video](https://github.com/Rethink-JS/rt-video)

---

by **Rethink JS** <br>
[https://github.com/Rethink-JS](https://github.com/Rethink-JS)