@hevcjs/hlsjs-plugin

HEVC/H.265 playback plugin for hls.js. Transparently transcodes HEVC segments to H.264 via WebAssembly when native HEVC is unavailable. When native HEVC is available, the plugin detects it and does nothing.

Install

npm install @hevcjs/hlsjs-plugin hls.js

Usage — bundled (Vite, Webpack, etc.)

Copy the static assets from @hevcjs/core to your public directory:

cp node_modules/@hevcjs/core/dist/transcode-worker.js public/
cp node_modules/@hevcjs/core/dist/wasm/hevc-decode.js public/
cp node_modules/@hevcjs/core/dist/wasm/hevc-decode.wasm public/

Then:

import Hls from 'hls.js';
import { attachHevcSupport } from '@hevcjs/hlsjs-plugin';

const video = document.querySelector('video');

// Must run BEFORE `new Hls()` — hls.js filters levels against
// MediaSource.isTypeSupported at manifest parse time.
await attachHevcSupport({
  workerUrl: '/transcode-worker.js',
  wasmUrl: '/hevc-decode.js',
});

// Classic MediaSource is required by the transcoding path. iPhone Safari only
// has ManagedMediaSource: pinning classic MSE there would leave hls.js with no
// MediaSource at all and playback would fail, so keep its default.
const hls = new Hls({
  ...(typeof MediaSource !== 'undefined' ? { preferManagedMediaSource: false } : {}),
});
hls.attachMedia(video);
hls.loadSource('https://example.com/stream/playlist.m3u8');

preferManagedMediaSource: false keeps hls.js on classic MediaSource, which the transcoding path requires. Guard it on typeof MediaSource !== 'undefined': iPhone Safari exposes only ManagedMediaSource, and pinning classic MSE there leaves hls.js without any MediaSource, which breaks playback. Left on its default, iPhone plays HEVC natively.

Usage — from a CDN (zero build)

<script type="module">
  import { attachHevcSupport } from 'https://esm.sh/@hevcjs/hlsjs-plugin@0';

  const video = document.querySelector('video');

  await attachHevcSupport({
    workerUrl:     'https://unpkg.com/@hevcjs/core@1/dist/transcode-worker.js',
    wasmUrl:       'https://unpkg.com/@hevcjs/core@1/dist/wasm/hevc-decode.js',
    wasmBinaryUrl: 'https://unpkg.com/@hevcjs/core@1/dist/wasm/hevc-decode.wasm',
  });

  // Classic MediaSource is required by the transcoding path. iPhone Safari only
// has ManagedMediaSource: pinning classic MSE there would leave hls.js with no
// MediaSource at all and playback would fail, so keep its default.
const hls = new Hls({
  ...(typeof MediaSource !== 'undefined' ? { preferManagedMediaSource: false } : {}),
});
  hls.attachMedia(video);
  hls.loadSource('https://example.com/stream/playlist.m3u8');
</script>

wasmBinaryUrl is required when assets live on a different origin than the page — Emscripten otherwise resolves the .wasm relative to the worker's blob: URL and fails.

API

attachHevcSupport(config?): Promise<HevcHlsPluginHandle>

Probes native HEVC support (by actually creating an HEVC SourceBuffer, not just isTypeSupported), checks WebCodecs H.264 encoding, then installs the MSE intercept. Returns a callable handle: invoke it (or handle.uninstall()) to tear everything down; handle.attachComputeAware(hls) wires the compute-aware ABR feedback loop (caps hls.autoLevelCapping when the device can't transcode the current level in real time — on by default, pass adaptiveCompute: false to opt out).

Unlike the dash.js plugin, no player instance is needed: hls.js keeps HEVC levels in its ladder as long as the (patched) MediaSource.isTypeSupported accepts them.

| Option | Type | Description | |---|---|---| | workerUrl | string | Transcode worker script URL. When set, transcoding runs off the main thread (recommended). | | wasmUrl | string | URL of the Emscripten glue script (hevc-decode.js). | | wasmBinaryUrl | string | URL of the .wasm binary — needed for cross-origin/CDN setups. | | forceTranscode | boolean | Transcode even when native HEVC is available (testing). Default false. | | adaptiveCompute | boolean \| object | Compute-aware ABR: true/omitted = on, object = decider tuning, false = off. | | logLevel | string | 'debug' \| 'info' \| 'warn' \| 'error' \| 'silent'. |

Scope and compatibility

• Tested against hls.js 1.7.x (the declared peer range >=1.4.0 is not fully exercised — 1.6.6 changed how hls.js drives SourceBuffer.timestampOffset, and this plugin is designed for the current behavior).
• Supported today: HLS fMP4 streams — video-only, demuxed-audio and muxed audio+video renditions.
• For muxed audio+video segments (single audiovideo SourceBuffer, codecs="hvc1...,mp4a...") the HEVC video is transcoded and the AAC audio is passed through, re-muxed into one combined A/V segment. Note: the muxed path runs on the main thread (the worker fast path is video-only), and only AAC audio pass-through is implemented. Validated end-to-end with a muxed test stream. HEVC-in-MPEG-TS is untested.
• Compute-aware ABR is wired via handle.attachComputeAware(hls) — on by default.

License

MIT