Playing a video

Transcoding gives you one URL. This page is what to do with it.

The URL you need

Once an asset reaches COMPLETED, fetch it and take video.hls_manifest_url. That single URL is the whole thing — an HLS master playlist listing every quality we produced.

{
  "asset": {
    "status": "COMPLETED",
    "video": {
      "hls_manifest_url": "https://…/hls-f2975d/master-5799955.498679052.m3u8"
    },
    "renditions": [ { "quality": "P480", "playlist_url": "…" } ]
  }
}

In a browser

Browsers do not understand HLS natively, with the exception of Safari and iOS. A player library bridges the gap by fetching the playlist and feeding segments to a normal <video> element.

<video id="player" controls playsinline style="width:100%"></video>

<script src="https://cdn.jsdelivr.net/npm/hls.js@1"></script>
<script>
  const video = document.getElementById('player');
  const src = 'https://…/master-5799955.498679052.m3u8';

  if (video.canPlayType('application/vnd.apple.mpegurl')) {
    video.src = src;              // Safari and iOS play HLS themselves
  } else if (window.Hls && Hls.isSupported()) {
    const hls = new Hls();
    hls.loadSource(src);
    hls.attachMedia(video);
  }
</script>

Any HLS-capable player works — hls.js, Shaka Player, Video.js. StreamOS’s own dashboard uses Shaka, because it also handles DASH.

On mobile and TV

Quality switching

The master playlist lists every rung with its bandwidth. Players switch automatically as the connection changes — you do not have to choose, and in most cases should not.

Access and DRM

A manifest URL is public. It is long and unguessable, but anyone holding it can play the video — there is no token, no expiry and no sign-in.

What that means in practice

Treat the URL as the secret. Do not put it in a public page source if the content is paid; fetch it from your own backend when a viewer is entitled to it, so the check lives with you rather than with the URL.

Videos uploaded with drm: true are the exception — the manifest itself is not what protects them. They produce DASH output instead of HLS (hls_manifest_url is null; use renditions[].dash_url), and every playback additionally needs a decryption licence, fetched fresh each time a viewer starts watching. The rest of this section is that flow.

Playing DRM content

The real licence server and its credentials never reach you or a viewer’s browser. You ask our API for a short-lived, single-purpose session_id; the player is then configured to fetch the actual licence through our own proxy, using that id instead. This is deliberate — a real licence credential, once captured off the wire, could otherwise be replayed directly against the licence server from anywhere, indefinitely, with nothing on our side able to tell.

Step 1 — Mint a session

curl -X POST https://api.streamos.in/api/public/v1/assets/oI1j0SfJK3v/drm-token/ \
  -H 'Authorization: Bearer sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"user_id": "viewer-42", "device": "Web"}'

{
  "success": true,
  "data": {
    "drm": {
      "session_id": "kx93F2ivQeM8bYh1nQ4z2VvJTz8oP1s6",
      "device": "Web"
    }
  }
}

Step 2 — Point your player at our proxy, not the licence server

A session_idis not a licence — it is what unlocks one. Configure your DRM-capable player (Shaka Player, ExoPlayer, AVFoundation…) with these two URLs built from it, and the player fetches the actual licence itself the moment it needs to decrypt:

player.configure({
  drm: {
    servers: {
      'com.widevine.alpha': `https://api.streamos.in/api/drm/license/${session_id}/`,
    },
  },
});
await player.load(dashManifestUrl);

FairPlay only. Returns the certificate as base64 text — decode it into bytes and pass it as advanced.serverCertificate for both com.apple.fps and com.apple.fps.1_0, before the licence server is ever called.

What a licence request actually returns

You never call this directly — the player does, using the URL from step 2. Included so a failure here means something concrete rather than a generic player error:

If it will not play