Migration checklist
Player migration checklist
Use this checklist to plan a player replacement end to end. It's the same sequence we use on real migrations, and it's deliberately short: most of the work is confirming what stays the same.
Work top to bottom, and prove each stage on the free plan before moving on. Nothing here touches your delivery stack.
Before you start
-
List every surface that plays video
Web, iOS and Android apps, Samsung Tizen, LG webOS and Android TV, set-top boxes, and any embedded players. Each surface is a place the player runs and a place to retest, so write them all down before you touch anything.
-
Record the current player and version
Note the player you are replacing and the plugins around it: a DRM connector such as KeyOS or EzDRM, an ad plugin such as FreeWheel or Google IMA, and an analytics SDK. Those plugins are the integration points you will map.
-
Collect the sources and manifests
Gather one URL per content type: an HLS playlist (.m3u8), a DASH manifest (.mpd), a Smooth Streaming manifest, and a live stream if you have one. A VOD movie, a live sports feed and a protected asset each behave differently.
-
Note the DRM systems and licence endpoints
Write down which of Widevine, PlayReady and FairPlay you use, with the licence server URL and authentication for each. Browsers are usually Widevine or FairPlay, TVs are usually Widevine or PlayReady.
-
Note the ad setup
Note whether ads run client-side or server-side, and the endpoints in use: a VMAP playlist, VAST tags, VPAID creatives, or a FreeWheel or Google IMA integration. Server-side insertion also means SCTE-35 markers in the live stream.
-
Note the analytics events you rely on
List the events your dashboards actually use: playback start, rebuffering, errors, quality changes and watch time. If a report breaks when an event goes missing, that event belongs on the list.
Build and configure
-
Create an account and a player
Sign up for the free plan, then open Players list in the panel and choose Create new. Name the player, pick a skin and colours in the configurator, save, and generate the player files. The build gives you an embed code and the player JavaScript source.
-
Embed the player on the page
You can embed Bradmax three ways. Use the JavaScript API, an HTML script element with data-bs-parent-id, or an iframe. The iframe is the quickest to drop in, but it has the smallest feature set, so use the JavaScript API when you need DRM or the full API.
-
Point the player at your own manifest
Give the player your source in the dataProvider object, or point dataSource at a JSON file that carries the media data. The source object takes the manifest URL, so HLS, DASH and Smooth Streaming all play as they are. If the JSON or the manifest sits on another domain, the response needs CORS headers.
-
Configure DRM
DRM is configured through the JavaScript API, not the iframe. The page must be served over HTTPS, with localhost the one exception, and KeyOS/BuyDRM and EzDRM need player v2.9.1 or later. Add your Widevine, PlayReady and FairPlay licence endpoints in the source DRM object.
DRM overview · Preparing the player · Default provider · KeyOS / BuyDRM · Cloud DRM
-
Configure ads
Ads go in the advertisement object, which takes a VMAP playlist, VAST breaks, or VPAID creatives. FreeWheel and Google IMA each have their own configuration object. If you embed with an iframe, the a.vmap query parameter is the ads path.
-
Confirm analytics
Bradmax analytics is on by default; set the GDPR options in bradmaxAnalytics. To send playback events to Google Analytics 4, add the googleAnalytics object with your measurementId and apiSecret.
-
Clear the common blockers before go-live
Most first-playback failures come down to three things. Missing CORS headers on the manifest or the data JSON. A stream served over plain HTTP. Autoplay that only works when the player starts muted.
Prove it, then switch
-
Retest the devices you support
Run the stream on the real targets: Chrome, Firefox and Edge on desktop, Safari and iOS, Android, and the TV models you ship such as Samsung Tizen, LG webOS and Android TV. A player that passes on your laptop can still fail on an older television.
-
Run a side-by-side on your own traffic
Play the new player alongside the old one on a slice of traffic and compare the numbers that matter: time to first frame, rebuffering ratio and error rate. Even a rough before and after is enough to catch a regression before go-live.
-
Switch the embed
Replace the old player reference with the Bradmax embed or build. For a JavaScript integration that is the bradmax.player.create call; for an iframe it is the generated player URL. The source, DRM and ad configuration stay the same.
-
Watch the first live event closely
Keep an eye on the first high-traffic event after the switch: concurrent viewers, rebuffering and errors. If one device misbehaves, check the common causes before escalating.
What this checklist assumes
It assumes you keep your current packaging, delivery and DRM. If you're also changing CDN, repackaging content or moving DRM providers, that's a larger project and worth sequencing separately from the player swap.
Replacing a specific open-source player? The migration guides go deeper on the concept mapping for hls.js, Shaka Player and Video.js. For the whole thing end to end, the TISA case study is a vendor replacement delivered in weeks across 6 leagues and 2 playback models.
Where to go next
Sources and method
- Migration guides Bradmax documentation for hls.js, Shaka Player and Video.js
- TISA case study Bradmax customer story, vendor replacement without interruption