Embed an HLS stream

# Embed an HLS stream in HTML

There are two mechanisms, and picking the wrong one is why the same three lines work in Safari and show a black box in Chrome. Safari decodes HLS itself; every other browser needs a library that feeds the stream into a video element through Media Source Extensions.

The snippets below cover both, plus the CORS rule that accounts for most of the failures people hit next.

## The short answer

If you only target Safari, iOS and Apple TV, a video element with the playlist URL as its src is enough. If you target a browser, use hls.js or a player that includes it. If you want to check a stream before writing any code, the online M3U8 player does the same job without a build.

## Safari and iOS: native HLS in a video element

Nothing else is needed on Apple platforms. The legacy type attribute is harmless and helps older Safari versions identify the playlist.

```
<video
  controls
  playsinline
  src="https://cdn.example.com/stream/master.m3u8"
  type="application/vnd.apple.mpegurl">
</video>
```

## Why the same snippet fails in Chrome

Chrome has no HLS decoder. Given an m3u8 URL in a video element it fetches the playlist, can't decode it, and stops. The element stays black and the visible page shows no error, which is why this failure is so often reported as "the stream is broken". It isn't; the browser is missing the format.

Media Source Extensions is the way around that. The page fetches the playlist and the segments itself, then pushes them into the video element as a media stream. hls.js is the smallest way to get that, and most commercial players wrap the same idea.

## Every other browser: hls.js

The first branch keeps Apple platforms on their native decoder, which is faster and avoids a library download. The second branch covers everything with Media Source Extensions. Check the console for the hls.js error event when a stream fails; it names the actual cause.

```
<script src="https://cdn.jsdelivr.net/npm/hls.js@1/dist/hls.min.js"></script>

<video id="player" controls playsinline></video>

<script>
  var video = document.getElementById('player');
  var src = 'https://cdn.example.com/stream/master.m3u8';

  if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src;
  } else if (window.Hls && window.Hls.isSupported()) {
    var hls = new window.Hls();
    hls.loadSource(src);
    hls.attachMedia(video);
    hls.on(window.Hls.Events.ERROR, function (event, data) {
      if (data.fatal) { console.error('HLS error', data); }
    });
  }
</script>
```

## The CORS rule that breaks most embeds

When JavaScript fetches the manifest, the browser applies the same-origin policy: the response must carry Access-Control-Allow-Origin for your page to read it, and so must every segment the player downloads afterwards. Origin servers that serve manifests through an API usually have the header; media segments served straight from storage often do not.

Nothing on the page can fix this. A proxy would, which is why so many "HLS player" sites quietly proxy streams through their own servers, and why that isn't something to hand your video to. If the header is missing, the stream owner adds it, or the embed won't work in Chrome no matter which player you choose.

Native playback on Safari isn't affected in the same way, because Safari decodes the stream itself rather than reading it with JavaScript. That asymmetry is the reason a stream can work on an iPhone and fail on a laptop.

## Which embed works where

| Target | Native video element | hls.js or a player |
| --- | --- | --- |
| Safari desktop and iOS | Yes | Also works, native is faster |
| Chrome, Edge, Firefox desktop | No | Yes |
| Android Chrome | No | Yes |
| Smart TV browsers | Sometimes | Model dependent, test the target |
| In-app WebViews | Platform dependent | Usually yes, if MSE is exposed |
| Browsers without MSE | Only with native HLS | No |

## Sizing the embed without layout shift

Give the video a ratio rather than fixed pixel dimensions, so the page doesn't reflow when metadata arrives. 16 by 9 is the default for most content; use 9 by 16 for vertical video.

```
<style>
  .hls-frame {
    width: 100%;
    max-width: 960px;
    aspect-ratio: 16 / 9;
    background: #000;
  }
</style>

<video class="hls-frame" id="player" controls playsinline></video>
```

## The Bradmax iframe embed

When you would rather not maintain the playback layer, the player is embedded as an iframe with the manifest URL in the query string. The generated code is in the client panel, documented in the iframe embed guide.

```
<iframe
  src="https://bradm.ax/build/202606/10/e1c1f29d59fb2a341df6fe3103a41b06338c2049/index.html?mediaUrl=https%3A%2F%2Fbradmax.com%2Fstatic%2Fvideo%2Ftos%2F440272.m3u8"
  width="640"
  height="360"
  frameBorder="0"
  allow="autoplay; encrypted-media"
  allowfullscreen></iframe>
```

## Protected streams are a different job

An encrypted HLS stream needs EME, DRM signalling in the manifest and a licence exchange before the first frame. That isn't something an embed snippet covers, because the licence request has to carry your authentication data and match the key system the device supports. The DRM capability tester shows which of Widevine, PlayReady and FairPlay this browser can use, and multi-DRM playback describes how one configuration covers all three.

## Where to go next

- [Online M3U8 player](https://bradmax.com/site/en/tool/m3u8-player)

- [HLS playlist inspector](https://bradmax.com/site/en/tool/hls-playlist-inspector)

- [Browser capabilities](https://bradmax.com/site/en/tool/browser-capabilities)

- [DRM capability tester](https://bradmax.com/site/en/tool/drm-capability-tester)

- [How to play an M3U8 file](https://bradmax.com/site/en/guides/how-to-play-an-m3u8-file)

- [HLS vs M3U8 vs DASH](https://bradmax.com/site/en/guides/hls-vs-m3u8-vs-dash)

- [What is an M3U8 file (the hub)](https://bradmax.com/site/en/hls-m3u8-intro)

## Frequently asked questions

### Can I embed an m3u8 stream in a plain HTML page?

Yes, in two ways. A video element with the playlist URL as its src plays HLS on Safari and iOS natively. Everywhere else you add a player library that uses Media Source Extensions, which is four lines of JavaScript with hls.js. A single snippet can't cover both without a library or a branch, so the guide shows the branch.

### Why does my embedded HLS video show a black box in Chrome?

Chrome can't play HLS natively. If the video element has the m3u8 URL and no library is attached, the element receives a stream it can't decode and stays black with no error visible to the user. The console usually shows a media error. Attach hls.js, or use the Bradmax player which does it for you.

### Why does the embedded stream fail with a CORS error?

The page is on your origin and the stream is on another one. A player that fetches the manifest with JavaScript needs Access-Control-Allow-Origin on the manifest and on every segment, and media segments often miss it because they are files rather than API responses. Only the stream server can fix this. A player can't proxy around it, and one that claims to is proxying your video through someone else.

### Do I need a player library for HLS on Android and Smart TV?

Android Chrome and most Smart TV browser engines don't decode HLS natively, so yes for the browser case. Native applications and some TV platforms do have built-in HLS support, which is a different integration path. The browser capabilities checker tells you what the specific engine supports.

### How do I embed a DRM-protected HLS stream?

The page needs EME, the manifest has to carry the DRM signalling, and the licence server has to accept the request. That's more than an embed snippet: the player handles the licence exchange, which is why protected playback is usually delegated to a player rather than written by hand. The DRM capability tester reports what the browser can decrypt.
