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.

## The migration, step by step

### Keep your manifests

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

### 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.

### 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.

### 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.

### 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.

### 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.

### 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 from Shaka Player](https://bradmax.com/site/en/guides/migrate-shaka-player-to-bradmax)

- [Migrate from Video.js](https://bradmax.com/site/en/guides/migrate-videojs-to-bradmax)

- [Open source vs commercial](https://bradmax.com/site/en/guides/open-source-vs-commercial-player)

- [Start free](https://bradmax.com/site/en/signup)

### 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.