rt-video

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

---

Table of Contents

• 1. Installation
  • 1.1 CDN (jsDelivr)
  • 1.2 npm
• 2. Quick Start
• 3. Activation Rules
• 4. Configuration (HTML Attributes)
• 5. Multiple Instances
• 6. Global API
• 7. Troubleshooting
• 8. License

---

1. Installation

1.1 CDN (jsDelivr)

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

1.2 npm

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:

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

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
GitHub: https://github.com/Rethink-JS/rt-video

---

by Rethink JS
https://github.com/Rethink-JS