Build with UniplayOS

Quickstart

Clone the repo, install dependencies, run the dev server.

# clone and install
git clone https://github.com/unitedevz/uniplayOs.git
cd uniplayOs
npm install

# start the dev server on :3000
npm run dev

Then open http://localhost:3000/player.html?url=https://example.com/video.mp4 to test a direct link, or /test.html to inspect how any URL resolves before wiring it up.

Resolver

Every URL passed to the player goes through Resolver.resolve(url) first. It looks at the URL, decides what kind of media it is, and picks a playback strategy plus a fallback chain to try if that strategy fails.

const resolver = new Resolver({ proxyBase: '/proxy' });

const result = resolver.resolve('https://cdn.example.com/stream.m3u8');

console.log(result.type);            // 'hls'
console.log(result.strategy);        // 'hls'
console.log(result.proxyRequired);   // true
console.log(result.fallbackChain);   // ['hls', 'proxy', 'mp4-fallback']

What resolve() returns

Proxy Endpoint

When a source needs to be proxied, the player requests it through /proxy instead of fetching it directly. This is what lets UniplayOS sidestep CORS and hotlink protection on the source, and forwards range requests so seeking still works.

fetch('/proxy?url=' + encodeURIComponent('https://cdn.example.com/clip.mp4'), {
  headers: { Range: 'bytes=0-' }
});

Behavior

Target validation

Loopback, private, link-local, carrier-grade NAT and IPv6 unique-local ranges (including IPv4-mapped and NAT64 forms) are blocked. Every redirect hop is validated again, and the address check also runs at connect time, so a hostname that resolves differently between the check and the request is still rejected.

HLS & DASH manifest rewriting

When the proxied URL is an HLS playlist (.m3u8) or a DASH manifest (.mpd), the proxy doesn't just stream it through — it rewrites every segment, sub-playlist, encryption key, alternate audio/subtitle track, I-frame playlist, low-latency part, and BaseURL reference inside it to route back through /proxy too. data: key URIs are left untouched. Without this, a manifest could load fine while its individual segments still hit the original (possibly blocked) host directly.

Templated DASH segments

DASH SegmentTemplate URLs contain placeholders such as $Number$, $Time$ and $RepresentationID$ that the DASH client fills in itself, so they can't be wrapped in a query string. The proxy rewrites them to a path form instead:

token is the base64url-encoded segment directory and rest is the remainder of the template, placeholders included. Once the client substitutes the placeholders, the server joins the two and fetches the segment. This route runs the same checks as /proxy: blocked private hosts, the host allowlist and the rate limit. A malformed or oversized token returns 400.

References are resolved through the nested BaseURL chain, as the DASH spec requires, and <Location> elements are rewritten so live manifest refreshes stay on the proxy. UTCTiming URLs are not proxied.

Caching & retries

Rewritten manifests are cached in memory for a few seconds per source URL, so repeated requests for the same live manifest don't refetch upstream every time. Check the X-Proxy-Cache response header (HIT or MISS) to see whether a given response came from cache. Failed upstream requests (network errors or a 5xx response) are retried once before the proxy gives up. Non-200 manifest responses are passed through uncached.

Player Params

The player at /player.html reads its source straight from the query string, so it can be deep-linked without any JavaScript.

Playlists

With more than one entry in sources (plus source, which sets the starting item), the player shows previous/next buttons and moves to the next item when one ends. Each change fires a trackchange event to the embedding page.

Subtitles

A CC button appears whenever subtitle tracks are available. Tracks come from three places: external files passed in subtitles, subtitle tracks declared in an HLS manifest, and text tracks in a DASH manifest. External files can be SRT or WebVTT; SRT is converted in the browser, and cross-origin files are fetched through /proxy. In a playlist, an item object can carry its own subtitles list, while the top-level subtitles attach to the starting item.

The last language you pick is remembered, and so is turning subtitles off. A remembered language wins over a track marked default, and a remembered Off wins over both. YouTube and Vimeo sources have their own caption controls and don't show the CC button.

Quality selector

HLS and DASH streams with more than one quality get a quality button next to the speed control. Auto lets the player adapt and shows the current level; picking a resolution pins it. Manual choices are remembered and re-applied to the closest level at or below the saved height. Plain files, YouTube and Vimeo don't show the button.

Keyboard shortcuts and gestures

Shortcuts work whenever the player has focus and you aren't typing in a field. Combinations with Ctrl, Cmd or Alt are left to the browser, and YouTube and Vimeo sources are driven through their own players, so only native, HLS and DASH playback is guaranteed.

Picture-in-picture

When the browser supports it, native, HLS and DASH playback show a picture-in-picture button next to fullscreen. The player sends a pictureinpicture message with { active } when it opens or closes. Embeds created with embed.js already allow it. If you write the iframe yourself, add picture-in-picture to its allow attribute. There's no embed method for it, because browsers only start picture-in-picture from a direct click inside the player.

Media controls

For native, HLS and DASH playback the player registers with the browser's Media Session API, so lock-screen and notification controls, media keys and Bluetooth headsets can play, pause, seek and move between playlist items. The title comes from the file name and the artist from the source host.

Downloading HLS and DASH streams

The download button in the player and the downloads page work for HLS and DASH too. The segments are fetched through /proxy, decrypted if needed, and joined into a file. In the player, the quality you picked is used (Auto takes the highest). On the downloads page it always takes the highest.

Chromium-based browsers (Chrome, Edge) save straight to disk through a save dialog, or a folder picker when there are two files, so size is not limited. Other browsers assemble the file in memory, up to 2 GB. Rate-limited segments are retried after the proxy's Retry-After delay, and the button turns into Cancel while a download runs.

Not supported: live streams, DRM-protected content, HLS encryption other than AES-128, and DASH streams with more than one period. Encrypted HLS needs a secure (HTTPS or localhost) page for the Web Crypto API.

Embed Script

Drop the embed script into any page and point it at a container element. It mounts an iframe running the UniplayOS player and talks to it over postMessage.

<div id="player" style="width:800px;height:450px;"></div>

<script type="module">
  import UniplayOS from "https://www.uniplayos.web.id/embed.esm.js";

  const player = new UniplayOS({
    container: "#player",
    source: "https://example.com/video.mp4",
    autoplay: false,
    debug: false,
    onReady() { console.log("ready"); },
    onPlay() { console.log("playing"); },
    onError(err) { console.error(err); }
  });
</script>

Constructor Options

Events

Pass any of these as callbacks in the constructor. Each fires from a postMessage the player sends back to the parent page.

Instance Methods

Once you hold a reference to the player instance, drive it programmatically.

player.play();
player.pause();
player.togglePlay();
player.seek(30);
player.setVolume(0.5);
player.toggleMute();
player.toggleFullscreen();
player.load('https://example.com/next.mp4', [{ src: 'https://example.com/next.en.srt', lang: 'en', label: 'English' }]);
player.next();
player.previous();
player.setQuality(720);
player.setQuality('auto');
player.setSubtitle('en');
player.setSubtitle('off');
player.setPlaybackRate(1.5);
player.setDebug(true);
player.destroy();

Supported Formats

Environment