Other HLS player

When using OptiView Player, the player automatically discovers a distribution and selects the appropriate streaming protocol. However, for certain use cases you may need direct access to the HLS manifest URL — for example, to cast to a Chromecast device, play on a set-top box, or integrate with a third-party player.

The HLS manifest is accessible at a deterministic URL:

https://discovery.theo.live/v2/distributions/<distributionId>/hls/main.m3u8

Replace <distributionId> with your distribution identifier.

For HLS-TS specifically, the manifest is available at:

https://discovery.theo.live/v2/distributions/<distributionId>/hls-ts/main.m3u8

warning

The HLS-TS URL only works if HLS-TS output is enabled on the engine. See the streaming protocols guide for more information.

Additional query parameters

When using OptiView Player, the player automatically detects the viewer's platform — such as their device type and operating system — and passes this context along when discovering a distribution. This information is used to evaluate distribution override rules.

When you request the HLS manifest directly, this automatic detection is not available. To make sure override rules are still evaluated correctly, you can provide the platform context manually as URL query parameters. These parameters work the same way as the distribution override matching criteria:

Parameter	Values	Description
deviceType	tv, mobile, desktop, other	The type of device the viewer is using.
sdkType	native, web	Whether the viewer is using a native SDK or a web-based player.
osName	apple, android, windows, roku, other	The operating system of the viewer's device.
profileId	any string	A custom profile identifier for advanced targeting.

For example, to identify the viewer as a Roku TV device:

https://discovery.theo.live/v2/distributions/<distributionId>/hls/main.m3u8?osName=roku&deviceType=tv

Token security

If token-based security is enabled on the distribution, every request to the manifest URL must include a valid JWT. When using a third-party player, provide the token as a token query parameter:

https://discovery.theo.live/v2/distributions/<distributionId>/hls/main.m3u8?token=<JWT>

The token can be combined with any of the platform query parameters above — for example, ?osName=apple&token=<JWT>.

See the token-based security guide for details on generating and signing tokens.

DRM

If DRM is enabled on the engine, the HLS manifest served at the URLs above is encrypted. When using OptiView Player, DRM is handled for you automatically. When you play through a third-party player, you are responsible for the DRM integration yourself — both requesting the manifest with the right encryption scheme and configuring license acquisition.

info

The platform uses EZDRM as its DRM service provider, so your player must be integrated with EZDRM.

Encryption schemes

The platform supports two encryption schemes:

• CENC — the default, because it is supported on most platforms.
• CBCS — required for playback on Apple devices (FairPlay).

Because CENC is served by default, a manifest requested directly on an Apple device will not play DRM-protected content. To receive a CBCS-encrypted manifest, pass osName=apple as a query parameter:

https://discovery.theo.live/v2/distributions/<distributionId>/hls/main.m3u8?osName=apple

License acquisition URLs

Configure your player with the license acquisition URL that matches the encryption scheme it is using, so it can request decryption licenses from the DRM license server:

• Widevine and PlayReady — for CENC-encrypted streams.
• FairPlay — for CBCS-encrypted streams (Apple devices). FairPlay additionally requires a certificate URL.

Retrieve the license acquisition URLs for a channel with the Get EZDRM content protection configuration endpoint:

GET https://api.theo.live/v2/channels/{channelId}/drm/config/ezdrm

The response contains the license acquisition URL — and, for FairPlay, the certificate URL — for each key system:

{
  "contentProtection": {
    "integration": "ezdrm",
    "widevine": {
      "licenseUrl": "<widevine-license-url>"
    },
    "playready": {
      "licenseUrl": "<playready-license-url>"
    },
    "fairplay": {
      "licenseUrl": "<fairplay-license-url>",
      "certificateUrl": "<fairplay-certificate-url>"
    }
  }
}