From db817703a6a2b9cb20588e104256dd40d0cfe0e2 Mon Sep 17 00:00:00 2001 From: "Thingvall, Nils" Date: Mon, 1 Jun 2026 13:18:51 -0600 Subject: [PATCH 1/3] Added a section for the MediaKind connector --- sidebarsTheoplayer.ts | 14 ++ ...01-getting-started-mediakind-connector.mdx | 122 ++++++++++++++++++ .../roku/mediakind/02-API-reference.mdx | 73 +++++++++++ 3 files changed, 209 insertions(+) create mode 100644 theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx create mode 100644 theoplayer/connectors/roku/mediakind/02-API-reference.mdx diff --git a/sidebarsTheoplayer.ts b/sidebarsTheoplayer.ts index 4fe300a07c0b..085f843878dd 100644 --- a/sidebarsTheoplayer.ts +++ b/sidebarsTheoplayer.ts @@ -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', diff --git a/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx b/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx new file mode 100644 index 000000000000..2b5f9ae6e2d4 --- /dev/null +++ b/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx @@ -0,0 +1,122 @@ +--- +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 + +``` + +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 + + +``` + +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: "", + AuthorizationToken: "", + AzukiIMC: "", + DeviceProfile: "", + key_id: "", +} +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, when 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 +m.player.source = sourceDescription + +MediaKindSession = { + mediaId: "", + ApplicationToken: "", + sessionId: "", + ownerUid: "", + manifest_uri: rollCallResponse.manifest_uri, + cdns: rollCallResponse.cdns, +} + +m.MediaKindConnector.callFunc("startSession", MediaKindSession) +``` + +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 +``` diff --git a/theoplayer/connectors/roku/mediakind/02-API-reference.mdx b/theoplayer/connectors/roku/mediakind/02-API-reference.mdx new file mode 100644 index 000000000000..2fe30c655c3c --- /dev/null +++ b/theoplayer/connectors/roku/mediakind/02-API-reference.mdx @@ -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. | From ed2898b5d7b84dec057d670765dc1e3d86f8bcbc Mon Sep 17 00:00:00 2001 From: "Thingvall, Nils" Date: Mon, 1 Jun 2026 13:22:43 -0600 Subject: [PATCH 2/3] Fixing casing --- .../01-getting-started-mediakind-connector.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx b/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx index 2b5f9ae6e2d4..4b91d1e389f3 100644 --- a/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx +++ b/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx @@ -56,15 +56,15 @@ end sub ```brightscript m.player = m.top.findNode("THEOPlayer") -m.MediaKindConnector = m.top.findNode("THEOMediaKindConnector") -MediaKindConfig = { +m.mediaKindConnector = m.top.findNode("THEOMediaKindConnector") +mediaKindConfig = { requestBaseUrl: "", AuthorizationToken: "", AzukiIMC: "", DeviceProfile: "", key_id: "", } -m.MediaKindConnector.callFunc("configure", m.player, MediaKindConfig) +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 @@ -74,7 +74,7 @@ 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: + 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 = { @@ -97,7 +97,7 @@ sourceDescription = { ```brightscript m.player.source = sourceDescription -MediaKindSession = { +mediaKindSession = { mediaId: "", ApplicationToken: "", sessionId: "", @@ -106,7 +106,7 @@ MediaKindSession = { cdns: rollCallResponse.cdns, } -m.MediaKindConnector.callFunc("startSession", MediaKindSession) +m.mediaKindConnector.callFunc("startSession", mediaKindSession) ``` 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. @@ -114,8 +114,8 @@ There are more properties available to add to the metadata, but `mediaId`, `Appl 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.mediaKindConnector.callFunc("destroy") +m.mediaKindConnector = invalid m.player.callFunc("destroy") m.player = invalid From 33fc3beddd77cf83acfe198eabb5b6e19fce545d Mon Sep 17 00:00:00 2001 From: "Thingvall, Nils" Date: Mon, 1 Jun 2026 14:01:29 -0600 Subject: [PATCH 3/3] Corrected order of operations --- .../mediakind/01-getting-started-mediakind-connector.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx b/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx index 4b91d1e389f3..b87d24f2d155 100644 --- a/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx +++ b/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx @@ -92,11 +92,9 @@ sourceDescription = { } ``` -7. Next, when 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: +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 -m.player.source = sourceDescription - mediaKindSession = { mediaId: "", ApplicationToken: "", @@ -107,6 +105,7 @@ mediaKindSession = { } 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.