@convertly-sh/player

Official Convertly video player with HLS playback, custom controls, optional branding, and playback analytics.

npm: @convertly-sh/player · Docs: docs.convertly.sh/docs/video-player · Demo: convertly.sh/demo/player

Install

npm install @convertly-sh/player

For React:

npm install @convertly-sh/player react react-dom

Package exports

| Import | Purpose | | --- | --- | | @convertly-sh/player | Vanilla mount API, HLS helpers, analytics | | @convertly-sh/player/react | ConvertlyVideo component | | @convertly-sh/player/styles.css | Required player styles | | @convertly-sh/player/assets/logomark-cutout.svg | Default branding asset |

React

import { ConvertlyVideo } from "@convertly-sh/player/react";
import "@convertly-sh/player/styles.css";

export function StreamPlayer({ stream }) {
  return (
    <ConvertlyVideo
      manifestUrl={stream.hlsManifestUrl}
      posterUrl={stream.posterUrl}
      playbackId={stream.playbackId}
      captions={stream.captions}
      chapters={stream.chapters}
    />
  );
}

The bundled logomark cutout appears by default. Override or remove it:

<ConvertlyVideo manifestUrl={url} branding={{ logoUrl: "https://yoursite.com/logo.svg" }} />
<ConvertlyVideo manifestUrl={url} branding={false} />

Vanilla JS

import { mountConvertlyPlayer } from "@convertly-sh/player";
import "@convertly-sh/player/styles.css";

const player = mountConvertlyPlayer(document.getElementById("player")!, {
  manifestUrl: "https://cdn.convertly.sh/video/v1/pb_.../master.m3u8",
  playbackId: "pb_...",
});

// player.destroy() when unmounting

Features

• HLS adaptive streaming via hls.js (Safari native HLS fallback)
• Quality menu, captions, chapters, scrub previews (VTT spritesheets)
• Theme tokens, skip buttons, PiP, fullscreen, resume playback
• Overlay and control-bar slots for custom UI
• Playback analytics when playbackId is set

See the full documentation for options, signed playback, and advanced APIs (attachHls, bindPlaybackAnalytics).

License

MIT