NAV
     

Anvato Player SDK for Roku

The Anvato SDK is designed for exclusive use of media companies who use Anvato’s video processing infrastructure for video on demand and live linear video. Anvato’s SDK for Roku provides secure backend communication, analytics and rich live stream metadata for Roku application developers and supports monetization through server side ad stitching. This document specifies the Anvato Roku SDK features and describes the integration requirements. Integration Anvato SDK is BrightScript based. The SDK is composed of two components: (i) the core library and a (ii) convenience player screen, which also serves as the reference application.

Features

Server-side Ad-Stitch

Monetize your videos from MCP using any VAST/VMAP compatible ad server.

Ad-Policy Enforcement

Seamless playback during ad-break view policy enforcements.

Plugins

Adobe Heartbeat, Nielsen, and other plugins.

Quick Start Instructions

anvato_cfg = {
    anvack        : "<your application specific anvack key>"
    security_key  : "<your security key>"
    callback_func : callbackFromAnvatoSDK
    callback_arg  : <the opaque object passed to the callback_func as an argument>
    vendors    : {
        adobe_heartbeat : true
    }
    post: {
        ads : {
            freewheel : {
                video_asset_id  : "<included in your feed/data source>"
                network_id      : "<included in your feed/data source>"
                site_section_id : "<included in your feed/data source>"
                profile_id      : "<included in your feed/data source>"
            }
        }
        user : {
            device  : "roku"
            adobepass : {
                mvpd        : "<included in your feed/data source>"
                requestor   : "<included in your feed/data source>"
                resource    : "<included in your feed/data source>"
                short_token : "<if available, to be filled after authorization>"
            }
        }
    }
}

Step 1) Create a local configuration object anvato_cfg where the fields are

Var Desc
anvack provided by Anvato.
security_key provided by Anvato.
vendors Specify which 3rd party libraries you would like enabled. Current version only supports "adobe_heartbeat".
callback_func The function that receives the event callbacks from the Anvato SDK. The prototype is as follows: Sub cb_func ( event as string, event_data as object, arg as object, anvato as Object ) This will be detailed in the following sections.
callback_arg This will be passed to your callback_func as the arg parameter.
post Contents are application specific and the SDK will simply pass these fields through to the backend APIs.

Step 2) Receive the remote configuration

remote_cfg = anvLoadConfig(anvato_cfg)

Call anvLoadConfig with the static configuration to retrieve the remotely hosted application configuration. You should call this once when application loads. This configuration is fairly static, but we recommend that you not cache it on persistent storage for more than a day.

Store a reference to this remote configuration in the app as it will be passed to each video playback session.

Step 3) Start video playback

spec = {
   media_type: "vod"
   media_id: "115123"
   start: 0
}

anvPlayVideo(remote_cfg,anvato_cfg,spec)

Create a video specification object, spec, where the fields are

media_type can be "vod" or "live".
media_id determined from your content feed.
start For "vod" videos start can be non-zero, which marks the initial seek point in the video.

then call anvPlayVideo to start the playback.

Step 4) Messages/Event Handling

Anvato SDK has port s which are not exposed to the app. Therefore the application must give the Anvato SDK the opportunity to poll these ports for new messages. This is typically done by a timeout based message loop. Here is the suggested message processing loop for your main video playback screen:

while true
    msg = wait ( 20, port )

    ' your own processing
    ' myAppProcessMessage ( msg )

    ' let anvato message handler poll, too
    anvato.Tick()
end while

As Anvato SDK processes video events, it will generate its own events and surface them to the application via the callback_func provided in the configuration.

VOD Playback Reference

Playback Progress

event = "videoProgress"
event_data =
{
    section_type: ("content" or "ad")
    position: (playback position in terms of seconds)
}

anvPlayVideo() will start the playback when it is called. As the playback progresses, the callback_func() will be called with video events and caption events.

Playback progress is sent with the videoProgress event which are delivered about every second.

If section_type is ad, then the following fields will also exist.

ads_in_break (number of ads in this break)
ad_no (current ad number in the break)
break_duration (total duration of the break in seconds)
pos_in_break (current time spent in the break in seconds)

Drawing a Scrubber

Use the timeline = getTimeline() function to learn the details of the ad spots and the video duration.

The timeline object is as follows:

timeline = {
    duration : (duration of the video)
    breaks :[
        {
            start    : (start time of the break in seconds)
            duration : (duration of the break in seconds)
            watched  : (set to true if the user has watched this break)
        }
        ,
        (more break objects)
    ]
}

Applications can use the "videoProgress" callback and the getTimeline() function to render an advanced scrubber bar.

Seek UI/Fast forward and Rewind Thumbnails

thumb =
{
    rect: {x:, y:, w:, h:}
    url : "(a cached thumbnail url)"
}

Use thumb = getThumb ( ts ) function to request a low resolution thumbnail of the image at time ts in seconds.

You must use thumb.rect as the SourceRect and thumb.url as the url of the Roku Content-Metadata (http://sdkdocs.roku.com/display/sdkdoc/Content+Meta-Data) object.

If thumbnail is not available at the time of request, getThumb() will return invalid.

Playback events

Anvato SDK passes the video events to the application via the callback_func with event = "roVideoPlayerEvent". This includes video start, network buffering, video end and other events.

This event is identical to the standard roVideoPlayerEvent, so you can use this callback to determine when the playback has ended or to detect issues.

Playback control

Pause Playback anvato.videoPause ( )
Resume Playback anvato.videoResume ( )
Seek Video anvato.videoSeek ( ts_msec )

Media information

To receive the media information about the requested video use anvato.getMediaInfo(), which returns a media information object.

// media information object:
{
    image: (url of the poster image associated with this video, if any)
    title: (title of this video, if any)
    description: (description of the video, if any)
    tags: (tags of the video, if any)
}

Windowing/Fullscreen

Use anvato.setDestinationRect(rect) to adjust the play window.

Live Playback Reference

anvPlayVideo() will start the playback when it is called. As the playback progresses the callback_func() will be called with video events and caption events.

Playback Control

Pause Playback anvato.videoPause()
Resume Playback anvato.vdeoResume()
Seek anvato.videoSeek()

Live Schedule Information

To receive the detailed event information about the current live stream, use anvato.getCurrentMetadata(media_id, timeout) where

media_id (channel identifier)
timeout (timeout in milliseconds.

media_id can be different than the current playing channel.

If timeout is 0 this becomes an asynchronous call and returns invalid, this does not mean the call has failed. The result of the asynchronous request is delivered to the callback_func() with receivedCurrentMetadata event. In that case event_data will contain all of the metadata and custom metadata as defined in MCP. This includes start time, end time, title, and next events.

If timeout is non-zero this becomes a synchronous call and it will block until the request is complete and returns the event_data object instead.

Playback Events

Anvato SDK passes the video events to the application with the roVideoPlayerEvent. This includes video start, buffering, video end and other events. This event is identical to the standard roVideoPlayerEvent, so you can use this callback to determine buffering progress, user playback actions has ended, and network or playback issues.

Closed Captions

The callback_func() will be called with roCaptionRendererEvent, where msg.getMessage() contains the caption text.

If no text is received but the callback is called, then the app should clear the currently displaying captions.

Metadata Queries

Query currently airing event and the upcoming events:

anvato.getCurrentMetadata ( media_id as String, timeout as integer )

This function returns an object with detailed metadata information about the current event and next four events. Note that each channel has a different media_id, you should query each channel separately if needed. Note that you can execute only one asynchronous query of the same type at a time. You have to wait until the outstanding query to complete before execute the next one of the same type.

You can execute different type queries in parallel.

If timeout = 0 then this function will be executed in a non-blocking manner, otherwise pass timeout in milliseconds after which the call will abort with error.

Query arbitrary event metadata:

anvato.getEventMetadata ( event_id as String, timeout as integer )

This function returns the metadata for a given event_id. If timeout = 0 then this function will be executed in a non-blocking manner, otherwise pass timeout in milliseconds after which the call will abort with error.

API Reference

Function Reference

anvLoadRemoteConfig ( pars as Object ) as Object

anvato = anvPlayVideo ( rcfg as Object, lcfg as Object, spec as Object ) as Object

anvato.setDestinationRect ( rect as Object )

anvato.tick ( )

anvato.getThumb ( ) as Object

anvato.getTimeline ( ) as Object

anvato.getMediaInfo ( ) as Object

anvato.videoSeek ( time_milli_seconds as integer )

anvato.videoPause ( )

anvato.videoResume ( )

anvato.getCurrentMetadata ( media_id as String, timeout as integer )

anvato.getEventMetadata ( event_id as String, timeout as integer )

Callback Reference

receivedCurrentMetadata

Callback received for the getCurrentMetadata() function

If event_data is invalid, the call has failed, otherwise event_data a complex object with numerous core and custom fields.

The event_data also includes up to 4 upcoming events information as well.

receivedEventMetadata

Callback received for the getEventMetadata() function

If event_data is invalid the call has failed, otherwise this is a rich object with numerous core and custom fields.

foundStreamEventID

Callback received for in-stream events. If the current event changes mid-stream you can rely on this callback to detect this change and update the metadata accordingly.

event_data = {
    event_id : "110973"
}

roVideoPlayerEvent

Callback received from the internal roVideoPlayer, except isPlaybackPosition() events

roCaptionRendererEvent

Callback received from the internal player's caption renderer.

videoProgress

Video progress event including the advanced ad information.