Skip to content

Mediakind connector for roku #670

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
turbidwater wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Mediakind connector for roku #670

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
db81770
Added a section for the MediaKind connector
turbidwater Jun 1, 2026
ed2898b
Fixing casing
turbidwater Jun 1, 2026
33fc3be
Corrected order of operations
turbidwater Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions sidebarsTheoplayer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,20 @@ const sidebars: SidebarsConfig = {
},
items: [{ type: 'autogenerated', dirName: 'connectors/roku/mux' }],
},
{
type: 'category',
label: 'MediaKind',
description: 'Integrate with MediaKind.',
customProps: {
icon: 'mediakind',
},
link: {
type: 'generated-index',
title: 'MediaKind Connector for Roku',
slug: 'connectors/roku/mediakind',
},
items: [{ type: 'autogenerated', dirName: 'connectors/roku/mediakind' }],
},
],
}),
'api-reference/roku',
Expand Down
121 changes: 121 additions & 0 deletions theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
---
sidebar_label: Getting started
sidebar_custom_props: { icon: '🚀' }
---

# Getting started with the MediaKind Connector for the Roku SDK

Here's how to get started integrating the MediaKind Connector with the THEOplayer Roku SDK.

## Prerequisites

In order to set up the MediaKind Connector in your Roku application, you'll need the following:

- OptiView Live integration
- An app with the THEOPlayer SDK for Roku already integrated, see our [Getting Started guide](https://www.theoplayer.com/docs/theoplayer/getting-started/sdks/roku/getting-started/).

## Integration

1. First you must download the THEO MediaKind Connector as a component library. Add a ComponentLibrary node to your MainScene.brs file, giving it an id of `THEOMediaKindConnector` and providing the URI for the THEOMediaKindConnector.pkg. Replace the `{SDK_VERSION}` tag with the version of the THEO Roku SDK you're using. The earliest version of the connector is 10.9.0:

```xml
<ComponentLibrary id="THEOMediaKindConnector" uri="https://cdn.myth.theoplayer.com/roku/{SDK_VERSION}/THEOMediaKindConnector.pkg" />
```

2. Then in the Brightscript file for your MainScene, listen for the loading of the ComponentLibrary to complete by observing the `loadStatus` field.

```brightscript
sub Init()
THEOMediaKindNode = m.top.findNode("THEOMediaKindConnector")
THEOMediaKindNode.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

sub onLibraryLoadStatusChanged(event as object)
THEOMediaKindNode = event.getROSGNode()

if THEOMediaKindNode = invalid
return
end if

if THEOMediaKindNode.loadStatus = "ready"
' Success
else if THEOMediaKindNode.loadStatus = "failed"
? "Failed to load component library, please check URL. "; THEOMediaKindNode.uri
end if
end sub
```

3. Add the THEOMediaKindConnector component to the SceneGraph file where your THEOPlayer is defined.

```xml
<THEOsdk:THEOplayer id="THEOplayer" controls="true" />
<THEOMediaKindConnector:THEOMediaKindConnector id="THEOMediaKindConnector" />
```

4. Then in the Brightscript file, configure the connector by calling the configure method, passing the player instance and your MediaKind configuration.

```brightscript
m.player = m.top.findNode("THEOPlayer")
m.mediaKindConnector = m.top.findNode("THEOMediaKindConnector")
mediaKindConfig = {
requestBaseUrl: "<MY_MK_BASE_URL>",
AuthorizationToken: "<MY_MK_STS_TOKEN>",
AzukiIMC: "<MY_MK_AZUKI_IMC>",
DeviceProfile: "<BASE64_ENCODED_DEVICE_INFO>",
key_id: "<MY_MK_DRM_KEY>",
}
m.mediaKindConnector.callFunc("configure", m.player, mediaKindConfig)
```

5. Next, make your roll call to MediaKind to get the response for the media you're playing

```brightscript
rollCallResponse = makeMyMediaKindRollCall()
```

6. Construct your source description for playback. The player needs to be provided with a `theolive`-type stream description, which will initiate Dolby’s discovery and failover logic.
Currently, while still depending on OptiView ≤ v11.3 player SDK versions, the player needs to be configured with this Discovery v2-style URL:

```brightscript
sourceDescription = {
sources: [
{
' v2-support
src: "channel-1",

' v3-support; replace when supported on all platforms (v11.X)
' src: '1f17631a-861d-42c2-9105-d97de0ab9c06/channel-1',

type: 'theolive',
}
]
}
```

7. Next, before you start playing the asset, call the `startSession` method and pass it the metadata for the asset you're playing, including information from the roll call response:

```brightscript
mediaKindSession = {
mediaId: "<MY_VIDEO_ID>",
ApplicationToken: "<MY_MK_TOKEN>",
sessionId: "<MY_SESSION_ID>",
ownerUid: "<MY_OWNER_ID>",
manifest_uri: rollCallResponse.manifest_uri,
cdns: rollCallResponse.cdns,
}

m.mediaKindConnector.callFunc("startSession", mediaKindSession)
m.player.source = sourceDescription
```

There are more properties available to add to the metadata, but `mediaId`, `ApplicationToken`, `sessionId`, and `ownerUid` are required. See [the THEOMediaKindConnector API docs](02-API-reference.mdx) for more properties that are available for MediaKind.

8. If you are exiting the player screen altogether, and destroying the player, make sure to destroy the connector at the same time, but before calling destroy on the player:

```brightscript
m.mediaKindConnector.callFunc("destroy")
m.mediaKindConnector = invalid

m.player.callFunc("destroy")
m.player = invalid
```
73 changes: 73 additions & 0 deletions theoplayer/connectors/roku/mediakind/02-API-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
sidebar_label: API reference
sidebar_custom_props: { icon: '*️⃣' }
---

# MediaKind Connector API

The attributes, methods and events for the THEOMediaKindConnector.

## Attributes

| Name | Type | Default | Access Permission | Description |
| ---- | ------ | ------- | ----------------- | ------------------- |
| id | string | | read,write | The id of the node. |

## Methods

| Method | Params | Description |
| ---------- | ------------------------------------------- | ------------------------------------------------------------ |
| configure | player: THEOplayer, config: MediaKindConfig | Add a player for playback and a configuration for MediaKind. |
| setSession | session: MediaKindSession | Sets the configuration for a MediaKind session. |
| destroy | none | Destroy the connector. |

### MediaKindConfig

The configuration for the MediaKind connector is the THEOMediaKindConfig interface.

| Name | Type | Default | Description |
| ------------------ | ------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| requestBaseUrl | string | | Base URL for Azuki API requests. For example, `https://ottapp-appgw-amp.prodb.nfl.tv3cloud.com/v1/client`. |
| AuthorizationToken | string | | Authorization token used for STS requests. |
| AzukiIMC | string | | Azuki IMC version. |
| DeviceProfile | string | | Base64-encoded information about the client device. |
| key_id | string | | DRM key identifier. |
| debug | boolean | false | Log debug info. |

### MediaKindSession

The configuration for a MediaKind session. This is meant to be the means to pass the response of the MediaKind roll call to the THEOMediaKindConnector.

#### Required fields

| Name | Type | Description |
| ---------------- | ------ | -------------------------------------------------------------------------------------------- |
| mediaId | string | Media identifier. |
| ApplicationToken | string | Service-specific token. Required for Live, Catchup, and Recording playback, but not for VOD. |
| sessionId | string | A unique session identifier. |
| ownerUid | string | Unique identifier of the owner of the asset being played. |

#### Optional fields

| Name | Type | Default | Description |
| -------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| manifest_uri | string | | URI of the manifest. |
| cdns | CDN[] | | CDN endpoints available for this session. |
| drm_type | string | | DRM method used for playback. Valid values are `widevine` or `playready`. |
| platform | string | | A descriptive platform string. |
| personal_info | string | | Base64-encoded JSON containing geographic and personal details. |
| beaconInterval | integer | 30 | The interval at which beacon requests should be executed, in seconds. |
| live | boolean | false | Whether the content is live. This property is used in the payload for beacons requests. |
| inHome | boolean | false | Whether the client is streaming from a home network. This property is used in the payload for beacons requests. |

### CDN

A CDN endpoint for playback of a session.

| Name | Type | Default | Description |
| -------------- | ------- | ------- | ------------------------------------------------- |
| name | string | | Name of the CDN. |
| retrieval_type | string | | Retrieval type of the CDN. For example, `static`. |
| base_uri | string | | Base URI for the CDN. |
| priority | integer | | Priority of the CDN. |
| threshold | integer | | Threshold of the CDN. |
Loading