Migration guide

Migrating from hls.js to Bradmax

hls.js is a great engine and plenty of production sites run on it. This guide is for the moment the integration around it has outgrown it: DRM to wire up, or a TV target to support.

The migration is deliberately small. Your manifests, DRM servers and ad tags stay exactly as they are; only the playback layer changes.

Start Free

The migration, step by step

  1. Keep your manifests

    Bradmax plays the same HLS master playlist hls.js loads. Nothing is re-encoded, repackaged or moved.

  2. Add the player source and a container

    Replace the hls.js script tag with the player source generated for your account, and give the player a container element. The embed code and iframe variant are produced in the client panel.

  3. Move the source into the player configuration

    The manifest URL moves from hls.loadSource() into dataProvider.source. Everything else about the source (DRM, ads, subtitles, thumbnails) is configured on the same object.

  4. Delete the media element wiring

    hls.attachMedia(video) and the manual <video> element are no longer needed: the player owns its media element and the quality ladder.

  5. Move DRM, if you had it

    Licence server URLs and authentication data move into the per-source drm object. Widevine, FairPlay and PlayReady are configured together, once, and applied to the matching manifests.

  6. Retarget your event handlers

    Your hls.js event listeners become Bradmax player events. Most recovery logic (retries, failover, quality switching) can be deleted rather than ported.

  7. Retest on your real devices

    Run the free plan against your own stream and the devices you actually support, including the TV or mobile target that triggered the migration.

Before: the hls.js integration

<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
<video id="video" controls></video>
<script>
  var video = document.getElementById("video");
  var hls = new Hls();

  hls.loadSource("https://cdn.example.com/stream/master.m3u8");
  hls.attachMedia(video);

  hls.on(Hls.Events.MANIFEST_PARSED, function () {
    video.play();
  });

  hls.on(Hls.Events.ERROR, function (event, data) {
    if (data.fatal) {
      // your recovery logic
    }
  });
</script>

After: the same stream in Bradmax 

<!-- The source URL is generated for your account in the client panel. -->
<script src="PLAYER_SOURCE.js"></script>
<div id="player" style="width: 100%; height: 100%; background: #000;"></div>
<script>
  var config = {
    dataProvider: {
      source: [
        { url: "https://cdn.example.com/stream/master.m3u8" }
      ],
      title: "My stream"
    }
  };

  window.bradmax.player.create(document.getElementById("player"), config);
</script>

The same streams, with DRM configured in Bradmax

// The licence servers and authentication data you already use, moved into the
// Bradmax source object. One entry per manifest you serve.
var authenticationXmlBase64Encoded = "PEtleU9TQXV0aGVudGljYXRpb25YTUw+...";

var drmConfig = {
  provider: "default",
  widevine: {
    laUrl: "https://drm-widevine.example.com/getkey",
    customData: authenticationXmlBase64Encoded
  },
  playready: {
    laUrl: "https://drm-playready.example.com/rightsmanager.asmx",
    customData: authenticationXmlBase64Encoded
  },
  fairplay: {
    laUrl: "https://drm-fairplay.example.com/getkey",
    certUrl: "https://drm-fairplay.example.com/cert/server-cert.der",
    customData: authenticationXmlBase64Encoded
  }
};

var config = {
  dataProvider: {
    source: [
      { url: "https://cdn.example.com/stream/manifest.mpd", drm: drmConfig },
      { url: "https://cdn.example.com/stream/master.m3u8", drm: drmConfig }
    ],
    title: "My stream"
  }
};

window.bradmax.player.create(document.getElementById("player"), config);

hls.js concepts and their Bradmax equivalents

Concept hls.js Bradmax
Script source hls.js from a CDN or npm bundle Player source generated per account in the client panel
Media element Your own <video> plus hls.attachMedia() Created and owned by the player inside its container
Source hls.loadSource(manifestUrl) dataProvider.source: [{ url: manifestUrl }]
DRM EME wiring and licence requests written by hand Per-source drm object with provider, laUrl, certUrl and customData
Quality and ABR hls.currentLevel and level events Built-in adaptive switching plus quality API events
Error handling Hls.Events.ERROR with your own recovery Player error events; retries, failover and recovery handled by the player
Ads Separate ad integration around the video element VAST, VMAP, VPAID, SGAI and server-side insertion in the player
Subtitles track elements or manual cue handling In-manifest subtitles plus VTT and SRT sidecar files
TV and mobile Not covered by hls.js alone Tizen, webOS, Android TV, Chromecast, AirPlay, Flutter and mobile WebViews

Worth knowing

  • Nothing in this guide requires a change to your manifests, your CDN or your DRM provider.
  • If you use hls.js for unprotected web-only playback today and that is all you need, staying put is a reasonable decision. See our open-source boundary guide.

Frequently asked questions

Do I have to change my HLS stream or manifest?

No. Bradmax plays the same master.m3u8 your hls.js integration already loads, including LL-HLS. The manifest URL is the only thing you carry over, unchanged.

What happens to my custom hls.js error handling?

Error handling moves from hls.js events to Bradmax player events, and most of it stops being necessary: the player handles recovery, endpoint failover and quality switching itself. Where you need to react, the JavaScript API exposes playback, error and quality events.

Can I keep my own controls and just use Bradmax for playback?

Yes. The player can be driven through its JavaScript API without the built-in skin, which is the closest match to a headless hls.js integration.

Does this add DRM if I did not have it?

It makes DRM straightforward rather than automatic. You still need licence servers and authentication data from your DRM provider; Bradmax supplies the certified connector and the configuration shape shown below.

References

  • Bradmax player configuration reference Bradmax player documentation, configuration.html
  • Bradmax DRM integration reference Bradmax player documentation, DRM default provider
  • Player source and embed code generation Bradmax client panel

Where to go next

Migrate against your own stream

The free plan is enough to prove the migration on the same manifest, the same DRM servers and your own devices. If you get stuck, an engineer answers.

Start Free