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..b87d24f2d155 --- /dev/null +++ b/theoplayer/connectors/roku/mediakind/01-getting-started-mediakind-connector.mdx @@ -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 + +``` + +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, 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: "", + ApplicationToken: "", + sessionId: "", + ownerUid: "", + 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 +``` 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. |