Roku Video Playback

The Cloud Solution relays video URLs from the app to be played on the Roku native video player.

Note: See Video DRM to learn how to specify DRM for your video content.

The following optional parameters are part of the Cloud Solution video player that can be enabled using the metadata prop in React Native. These parameters allow app developers to disable some of the automatic functionality of the custom video player.

Optional Metadata Parameter Description Default Value Notes
shouldAutoFocus A flag that tracks whether the client should automatically focus on the video player node. true By default, the Roku client sets focus on the video player when it’s created and when a video plays. This can cause issues when an app tries to render more than just the video and display other selectable elements on screen. Set this parameter to false to prevent the Roku client from setting focus on the video.
Note: This flag circumvents standard client focus logic and may cause unintended focus-related problems, so it should be used carefully.
handleBackKeyEvent A flag that tracks whether the video player should handle and consume back key events while active. true By default, the video player handles and consumes Roku client Back key events that stop and close the video player. This flag allows an app to bypass Back key events and handle them outside the video player.

See also the React Native implementation and C++ implementation.

You.i React Native Apps

For You.i React Native apps, video playback is triggered with the play() method of the Video or VideoRef components. Refer to those component descriptions for details.

The optional parameter can be added using the metadata prop as shown below:

  shouldAutoFocus: "false",
  handleBackKeyEvent: "false"

C++ Apps

For C++ apps, video playback is triggered by calling Play() on the C++ app’s CYIAbstractVideoPlayer. (A custom Roku-cloud player object is instantiated by CYIDefaultVideoPlayerFactory when the application is linked against the cloud library.)

This action sends playVideoCommand to the Roku client with the video URL, any set video metadata, and the scene node on which to play the video.

The parent-child relationships of the video player components are as follows:

  • VideoSurface: Cloud custom component (VideoSurface.xml stored server-side). Exported if CYIVideoSurfaceView is present in the scene. Present in the component library and referenced in CloudYouiLib.xml).
  • VideoPlayer: Cloud custom component (VideoPlayer.xml stored client-side). Created as a child of the in `main.brs` in response to `playVideoCommand`. Owns the `playerTask` which is also instantiated in `main.brs`, based on the ads object's `playerTaskName` field.
  • Video: Roku Component, the video node.

Video Metadata Specification

In addition to the video URL, the Roku player requires additional metadata, such as title. Use the CYICloud::ICloudInterface::SetVideoMetadata() API to provide this metadata. For details, see CYICloudInterface Class Reference. Depending on the client analytics libraries or ad service, additional metadata may be required.

The following is an example configuration:

// Add test metadata for the client player and analytics
CYIClientPlayer::VideoMetadata metadata;
metadata["Id"] = "My Asset Id - 1234";
metadata["ContentType"] = "movie";
metadata["Length"] = 10000; // seconds
metadata["Live"] =  "false"
metadata["Title"] = "My Video Title"
metadata["shouldAutoFocus"] = "false"
CYICloud::GetInterface().SetVideoMetadata(m_pPlayer, metadata);

Use the C++ app’s CYIAbstractVideoPlayer interface to specify the video URL as in a traditional CYIApp; for example:

m_pPlayer->Prepare("", CYIAbstractVideoPlayer::StreamingFormat::HLS, CYIAbstractVideoPlayer::PlaybackState::Paused);

Video Header Metadata Properties

Add special headers to a video request by adding them to the video metadata in the following format: <video header><delimiter><header key>:<header value>; for example:

metadata["videoheader<<drmHeader"] = "Your_DRM_key";.

Specifying the Bookmark Event Interval

By default, bookmark events are generated every 5 seconds. You can change that setting by using the BookmarkInterval key in the video metadata; for example::

metadata["BookmarkInterval"] = 3; // seconds;.

Exit on Video Complete

By default, the Cloud Solution assumes that video playback is a full-screen experience and the user is automatically navigated back once video completes.

However this automatic navigation back can be disabled by adding the ExitOnVideoComplete (false) metadata key to the video: for example:

(metadata.insert({"ExitOnVideoComplete", "false"});)

If your application disables exit on playback complete, you are responsible for managing the scene; for example focus, view presentation, and so on.

Get an Alert when Video Playback is Complete

Regardless of whether ExitOnVideoComplete is set, the Roku client issues a videocomplete event when playback has finished. Your application can capture and process this event by registering a lambda function as an event listener. We recommend that you register for the specific videocomplete event as shown below, although you can also register a generic listener for all events by passing in CYIString::EmptyString() as the first argument to RegisterDataListener.

//Register your listener
m_videoCompleteHandlerId = CYICloud::GetInterface().RegisterDataListener("videocomplete", [this](CYIString eventId, const yi::rapidjson::Document *pEvent) {
   return true;

After catching the videocomplete event, your function takes whatever actions are needed, then returns true if you’ve completely resolved that event, or false if you’d like the event to be passed to any registered generic event handlers.

Your application must also unregister its listener when you’re done with video playback. Failure to do so could result in a crash if further events of this type are triggered and your listener isn’t available to receive them.

//Unregister your listener
CYICloud::GetInterface().UnregisterDataListener("videocomplete", m_videoCompleteHandlerId);

Alternate Player Calling Sequence

Typically, an app exports the player screen which includes the video player and surface node. The app then sends a PLAY command with the surface node name to the Roku client, as shown in the following figure:


In the previous sequence, scene export and player instantiation are processed sequentially. In some cases however, the resulting time needed to reach the playable state may be too long to meet Roku certification requirements.

To reduce the time to reach the playable state, you can change the calling sequence so that scene export and player instantiation happen simultaneously, as shown in the following figure:


In this alternate sequence, player instantiation happens first. The player node on Roku is created with control: "prebuffer" and, as a result, video buffering can begin immediately. Actual playback begins with control: "play" after the scene is exported and the player node is attached to the surface node.

This alternate sequence can reduce the time needed to export the scene and get the player ready by up to a few seconds depending on the complexity of the player screen scene, the playback back-end server, and network circumstances.

Roku Voice Control Support

Voice controls enable applications to handle commands from the Roku voice remote and Roku mobile app. By default, all applications support the basic voice controls without any additional configuration, such as “fast forward”, “rewind”, “pause”, “resume”, and “replay”. To support enhanced voice controls, such as “seek”, “start over”, and “next”, the features have to be enabled by adding the following flags to the manifest file:

  • supports_etc_seek=1: for “seek” and “start over”
  • supports_etc_next=1: for “next”

For details on voice control, see the Roku article Implementing voice controls.