Insights with Azure Media Player Plugin
Options
All
  • Public
  • Public/Protected
  • All
Menu

Azure Media Player Hive Plugin Documentation

Usage:

<video id="video" class="azuremediaplayer amp-default-skin"/>
    <p class="amp-no-js">
        To view this video please enable JavaScript, and consider upgrading to a web browser that supports HTML5 video
    </p>
</video>
<script>
var player = amp('video', {
    controls: true,
    width: "640",
    height: "400",
    plugins: {
        hive: {
            // options listed in HiveComm.Options
            debugLevel: "notice",

            // optional callback for catching state
            HiveJava: {
                minVersion: "2014.1.1",
                onError: function (error) {
                    console.log("HiveJava onError ", error)
                    return true;
                },
                onActiveSession: function (a) {
                    console.log("HiveJava onActive", a);
                }
            }
        }
    }
});

player.src([
    {
        src: "<ORIGINAL CDN MANIFEST>",
        type: "application/vnd.ms-sstr+xml",
        sdnList: [
            {
                sdnName: "hive",
                sdnUrl: "<HIVE TICKET URL>"
            }
        ]
    },
]);
</script>

AMP Plugin Changelog

Changelog

Version compatibility with Hive Client:

Release Date min AMP version min Hive Client max Hive Client Plugin version and URL
December 15, 2015 1.5.0 2015.3 2016.1 1.0
January 16, 2016 1.6.0 2016.1 2016.1 1.1
April 18, 2016 1.6.0 2016.1 2016.1 2.0.1
July 1, 2016 1.6.0 2016.1 2016.1 2.1.1
August 25, 2016 1.6.0 2016.1 - 3.0.0

Notes

The basic usage is illustrated above. The hive plugin is called while the player is being initialized, and currently supports three types of distributions (techs):

  • HiveJava tech: distributes the video through the Java proxy client, works on every browser but supports only one video at the time.
  • HiveJS tech: distributes the video between browsers using WebRTC, works only on WebRTC Datachannel enabled browsers, supports one video per page.
  • StatsJS tech: no video distribution, only sends telemetry data for Insights analysis but works in every browser.

We currently have three different plugin packages with the following tech order combinations:

  • [HiveJava + StatsJS]: attempts video distribution using the Hive Java client if installed and ready, falls back to only telemetries otherwise.
  • [HiveJS + StatsJS]: attempts video distribution through the browser is supported, falls back to only telemetries otherwise.
  • [StatsJS]: only telemetries

The hiveTechOder option defines the order in which the above techs within a particular plugin package should be attempted.

Other combination packages can be built on demand depending on the player support.

Index

Modules

HiveComm

HiveComm:

API of Hive Comm player integration

Options

Options:

HiveJavaOptions

HiveJavaOptions:

Configurable Options valid only for the HiveJava Tech Usage:


 options: {
     HiveJava: {
         minVersion: "2015.1.100"
     }
 }
 

initTimeout

initTimeout: number

The Hive Java tech will fail if will not initiate a session before the timeout (in millisecond)

type

{number}

default

6000

minVersion

minVersion: string

minimum version of Hive Java allowed to run

type

{string}

default

{2013.1.1}

onActiveSession

onError

  • define a callback in case a specific tech could NOT initialize a session

    Parameters

    Returns boolean

    whether you want the plugin to try to initialize the session through the next techs

HiveTechOptions

HiveTechOptions:

Options specific for each tech
Usage:


 options: {
      StatsJS: {
          onError:function (error) {
              console.log(error)
              // return whether you want the plugin to try to
              // initialize the session through another tech
              return true
          },
          onActiveSession:function (session) {
              console.log("active hive session ", session)
          }
      }
 }

initTimeout

initTimeout: number

The tech will fail if will not initiate a session before the timeout (in millisecond)

type

{number}

default

10000

onActiveSession

onError

  • define a callback in case a specific tech could NOT initialize a session

    Parameters

    Returns boolean

    whether you want the plugin to try to initialize the session through the next techs

Options

Options:

General configurable options

constructor

debugLevel

debugLevel: string

configure the debug level for the Hive Player Plugin. The allowed levels are:

  • error
  • warn
  • notice
  • info
  • debug

default

notice

feedbackPeriod

feedbackPeriod: number

the feedback interval of statistic forwarding in millisecond.

type

{number}

default

2000

hiveTechOrder

hiveTechOrder: Array<string>

order in which the hive techs ({@link HiveComm.Tech.Techs}) will try to resolve a ticket Usually the default tech order depends on the plugin license:

  • [player].stats.hive.min.js default tech order is: ['StatsJS']
  • [player].hive.min.js default tech order is: ['HiveJava', 'StatsJS']
  • [player].hivejs.hive.min.js default tech order is: ['HiveJS', 'StatsJS']

it is possible to override the default tech order for example to disable HiveJava proxy and use directly only the StatsJS telemetry pack

type

{string[]}

monitorPort

monitorPort: number

Hive Java monitor port

type

{number}

default

8899 for http, 8898 for https

playerPort

playerPort: number

Hive Java player port

type

{number}

default

8999 for http, 8998 for https

silent

silent: boolean

if true activate the Hive-Tester Driver feedback to monitor the player status

type

{boolean}

default

false

useSessionCheck

useSessionCheck: boolean

enable or disable the check for other active sessions on Hive Java. Default off;

type

{boolean}

OptionsAMP

OptionsAMP:

Extended Optional configuration used by AMP

constructor

debugLevel

debugLevel: string

configure the debug level for the Hive Player Plugin. The allowed levels are:

  • error
  • warn
  • notice
  • info
  • debug

default

notice

feedbackPeriod

feedbackPeriod: number

the feedback interval of statistic forwarding in millisecond.

type

{number}

default

2000

hiveTechOrder

hiveTechOrder: Array<string>

order in which the hive techs ({@link HiveComm.Tech.Techs}) will try to resolve a ticket Usually the default tech order depends on the plugin license:

  • [player].stats.hive.min.js default tech order is: ['StatsJS']
  • [player].hive.min.js default tech order is: ['HiveJava', 'StatsJS']
  • [player].hivejs.hive.min.js default tech order is: ['HiveJS', 'StatsJS']

it is possible to override the default tech order for example to disable HiveJava proxy and use directly only the StatsJS telemetry pack

type

{string[]}

monitorPort

monitorPort: number

Hive Java monitor port

type

{number}

default

8899 for http, 8898 for https

playerPort

playerPort: number

Hive Java player port

type

{number}

default

8999 for http, 8998 for https

setupTimeout

setupTimeout: number

maximum time in millisecond allowed to Hive to resolve a ticket and initialize a HiveSession.

type

{number}

default

10000

silent

silent: boolean

if true activate the Hive-Tester Driver feedback to monitor the player status

type

{boolean}

default

false

streamingFormats

streamingFormats: Array<string>

streaming formats allowed for the rewriteUrl when using Hive

type

{string[]}

default

["DASH", "SMOOTH", "HLS-V3"]

useSessionCheck

useSessionCheck: boolean

enable or disable the check for other active sessions on Hive Java. Default off;

type

{boolean}

onHiveSessionError

  • define a callback to be called in case Hive could not activate an HiveSession for any of the sdnUrls.
    Although it is similar to HiveComm.Options.HiveTechOptions.onError which is called once for every time a specific tech could not resolve a HiveSession, this callback is called only when ALL the sdnUrls registered for Hive could not be resolved by any tech.

    Parameters

    Returns void

onSourceSetCompleted

  • onSourceSetCompleted(statusCode: number): void
  • define a callback to be called when the hive setup completes. This will give the status code generated by the Plugin Status Code Generator See: comm.hive.ts

    Status Codes Table

    Status Description Status Code (Hexadecimal) Status Code (Decimal)
    Success - Plugin Started with StatsJs Tech 0x00010000 65536
    Success - Plugin Started with Hive Java Tech 0x00100000 1048576
    Success - Plugin Started with HiveJS Tech 0x01000000 16777216
    Error - Hive Plugin not Allowed (amp only) 0x10000000 268435456
    Error - Ticket Not Resolved 0x20000000 536870912
    Error - Plugin Initialization Timeout 0x30000000 805306368

    Parameters

    • statusCode: number

    Returns void

UrlConfigurableOptions

UrlConfigurableOptions:

List of parameter names that can be passed to the page URL to setup correspondent plugin options.

hiveDebugLevel

hiveDebugLevel: string

hiveDebugLevel accepts a string value to initialize the debug console level. The valid values are the same as "debugLevel"

type

{string}

hiveMonitorPort

hiveMonitorPort: string

hiveMonitorPort url parameter accepts a numeric value for the monitor port binded by Hive Java client

type

{number}

hivePlayerPort

hivePlayerPort: string

hivePlayerPort url parameter accepts a numeric value for the player port binded by Hive Java client

type

{number}

hiveSilent

hiveSilent: string

hiveSilent url parameter accepts a boolean value to initialize a session as a silent test one. If true, HiveComm will start a periodic ping back to the local Hive Tester instance

type

{boolean}

HiveSessionErrorCode

HiveSessionErrorCode:

Error codes for failure in initializing Hive Sessions

GENERIC_ERROR

GENERIC_ERROR:

Generic Undefined Error

NO_TECH_AVAILABLE

NO_TECH_AVAILABLE:

No Tech available to resolve the ticket

NO_TECH_RESOLVED

NO_TECH_RESOLVED:

No available Tech could resolved the ticket

TECH_ERROR

TECH_ERROR:

Stopped resolving session on last tech onError

TICKET_ERROR

TICKET_ERROR:

The ticket could not be resolved

HiveSessionErrorString

HiveSessionErrorString:

Error messages corresponding to the HiveSessionErrorCode

Generic Undefined Error

Generic Undefined Error:

No Tech available to resolve the ticket

No Tech available to resolve the ticket:

No available Tech could resolved the ticket

No available Tech could resolved the ticket:

Stopped resolving session on last tech onError

Stopped resolving session on last tech onError:

The ticket could not be resolved

The ticket could not be resolved:

HiveTechErrorCode

HiveTechErrorCode:

Internal code of the Hive Tech Error

NOT_READY

NOT_READY:

the tech is not ready to resolve the ticket or initialize a HiveSession

PLUGIN_ERROR

PLUGIN_ERROR:

generic unspecified plugin error

SESSION_ERROR

SESSION_ERROR:

an error happened while initializing the HiveSession

TICKET_ERROR

TICKET_ERROR:

an error happened while resolving/verifying the ticket

TIMEOUT_ERROR

TIMEOUT_ERROR:

the tech didn't initialized the ticket before the timeout

VERSION_ERROR

VERSION_ERROR:

the tech doesn't satisfy the minimum version requirement

MainStatusCode

MainStatusCode:

This is the main status code, which will be used to generate the first 4 bits of the plugin status code

HIVE_NOT_ALLOWED

HIVE_NOT_ALLOWED:

The plugin is not allowed as SDN (only for AMP)

OK

OK:

The plugin initialization completed without errors

TICKET_NOT_RESOLVED

TICKET_NOT_RESOLVED:

It was not possible to resolve the ticket with the specified techs

TIMEOUT_RESOLVING_TICKET

TIMEOUT_RESOLVING_TICKET:

The plugin initialization and ticket resolving process timed out

Techs

Techs:

list of available Hive Techs

N.B. Please insert new techs just at the bottom of the list, in order to keep the status code for the plugins consistent, since it is dependent by the value of this enumeration Check test: 'when the hive plugin successfully starts, we get the code of the tech active'

HiveJS

HiveJS:

use the in-browser Hive client to retrieve the video from the CDN or the P2P Network HiveJS works only on browser that support WebRTC Datachannels (Chrome +38, Firefox +31 or Opera)

HiveJava

HiveJava:

use the Java installed Hive client to retrieve the video from the CDN or the P2P Network

HiveJsProxy

HiveJsProxy:

use the electron based installed HiveJS client to retrieve the video from the CDN or the P2P Network

StatsJS

StatsJS:

use only the browser telemetry package for Hive Insights

HiveSession

HiveSession:

Object containing information about the initialized Hive Session

id

id: string

the identifier of the session

manifest

manifest: string

the resolved manifest to be loaded by the player
It can either be the actual CDN manifest (Stats Pack/Hive.js) or the manifest proxied through Hive Java client.

tech

tech: string

the Hive technology that initialize this session

ticketUrl

ticketUrl: string

the url of the ticket

HiveSessionError

HiveSessionError:

Object containing information for failure in initializing Hive Session

code

detailedMessage

detailedMessage: string

message

message: string

ticketUrl

ticketUrl: string

HiveTechError

HiveTechError:

Object containing information about the Hive Tech Error that prevented the initialization of a Hive Session

constructor

code

message

message: string

ticketUrl

ticketUrl: string

getHiveSessionErrorMessage

HiveConfig

HiveConfig:

Module for Global Hive Configurations.

This configuration can be accessed directly, e.g.

HiveConfig.ErrorMonitor.enabled = false

ErrorMonitor

ErrorMonitor:

Overriding configurations for the Error Monitoring component. The ErrorMonitoring component provides RUM (Real User Monitor) and error tracking. This configurations are global per page.

enableKeyCombination

enableKeyCombination: boolean

Upload Log Key Combination enabled. If true, pressing the combination CTRL + SHIFT + X will upload the last 10 logs

default

true

enabled

enabled: boolean

Error Monitor enabled.

type

{boolean}

default

build-dependent

enabledErrorFilter

enabledErrorFilter: boolean

enable a filter for JS errors. If true, errors will be filtered based on the errorRegexFilter value. Set to true to send errors just in production.

type

{boolean}

default

false

enabledRUM

enabledRUM: boolean

Real User Monitor enabled. If true the component will monitor and send performance data of page and AJAX

type

{boolean}

default

false

errorRegexFilter

errorRegexFilter: string

Regex for filtering the errors based on the script url where the error was triggered.

type

{string}

default

'hivestreaming.com'

key

key: string

ErrorMonitor user key

type

string

version

version: string

ErrorMonitor reporting version

type

string

Classes

BufferDataStats

BufferDataStats:

currentBitrate

currentBitrate: number

FlashStats

FlashStats:

currentBitrate

currentBitrate: number

flashPlayer

flashPlayer: any

lastDownloadedBytes

lastDownloadedBytes: number

HiveAMP

HiveAMP:

constructor

  • new HiveAMP(player: any, options: any): HiveAMP

bufferDataStats

bufferDataStats: BufferDataStats

eventsRegistered

eventsRegistered: boolean

extendedStats

extendedStats: HivePlayerExtendedStats

flashStats

flashStats: FlashStats

lastEvent

lastEvent: PlayerEvents

loggerId

loggerId: string

options_

options_: Options

originalSourceList

originalSourceList: string

player

player: any

sdnName

sdnName: string

setupComplete

setupComplete: boolean

setupTimer

setupTimer: number

version

version: string

accountBufferDataDownloadCompleted

  • accountBufferDataDownloadCompleted(video: any, bufferData: any): void

accountBufferDataDownloadFailed

  • accountBufferDataDownloadFailed(video: any, bufferData: any): void

completeSetup

  • completeSetup(): void

filterEvents

  • filterEvents(event: PlayerEvents, eventObj?: any): void
  • special logic to filter events to avoid event loop spamming:

    • filter out 'SKIP' events

    Parameters

    • event: PlayerEvents
    • Optional eventObj: any

    Returns void

getActiveSession

getBufferLen

  • getBufferLen(): number

getCurrentTime

  • getCurrentTime(): number

getExtendedStats

  • getExtendedStats(): HivePlayerExtendedStats

getPlayerSource

  • getPlayerSource(): any

getPlayerTech

  • getPlayerTech(): any

getPlayerVersion

  • getPlayerVersion(): any

getPluginId

  • getPluginId(): string

getPluginName

  • getPluginName(): string

getPluginVersion

  • getPluginVersion(): string

getProtectionToken

  • getProtectionToken(srcObject: any): any

getSdnUrl

  • getSdnUrl(srcObject: any): any
  • check if hive is configured as available sdn for a source object and returns the ticket url associated

    Parameters

    • srcObject: any

    Returns any

getStatusCode

  • getStatusCode(): number
  • returns the current status code of the plugin

    Returns number

getStreamProtocol

  • getStreamProtocol(): StreamProtocol

getWindowSize

  • getWindowSize(): object

initStatusCode

  • initStatusCode(): void
  • initialize the status code of teh plugin to 0x00000000

    Returns void

isActive

  • isActive(): boolean

isFullscreen

  • isFullscreen(): any

isLive

  • isLive(): any

isSessionActive

  • isSessionActive(): boolean
  • true if the current watched manifest corresponds to the active HiveSession

    Returns boolean

logger

  • logger(): any

onActivateSession

  • onActivateSession(explicitPlayerSource?: string): boolean
  • Called after the initial metadata have been received from the player in order to activate the initialized Session

    Parameters

    • Optional explicitPlayerSource: string

    Returns boolean

onEndBuffering

  • onEndBuffering(): boolean
  • Returns boolean

onError

  • onError(errorCode: any, errorString?: string, closeSession?: boolean): void
  • Parameters

    • errorCode: any
    • Optional errorString: string
    • Default value closeSession: boolean = true

    Returns void

onEventFeedback

  • onEventFeedback(event: PlayerEvents, objEvent?: any): void
  • Parameters

    • event: PlayerEvents
    • Optional objEvent: any

    Returns void

onSetupTimeout

  • onSetupTimeout(): void
  • called when the player decided that the ticket resolve took too long and there is no need for it anymore

    Returns void

onStartBuffering

  • onStartBuffering(sendEvent?: boolean): void
  • Parameters

    • Optional sendEvent: boolean

    Returns void

options

pushOutputCode

  • pushOutputCode(): void

registerBufferDataStats

  • registerBufferDataStats(): void

registerEvents

  • registerEvents(): void

registerFlashVideoBufferStats

  • registerFlashVideoBufferStats(): void
  • legacy code for getting partial stats from FlashSS version before 1.7.0 rough measure of total bytes downloaded but no requests. bitrate switch working

    Returns void

resetSession

  • resetSession(): void
  • close the current active/initialized session, reset the active and initialized session values and reset the timers and stop the periodic stats

    Returns void

resetSetup

  • resetSetup(): void
  • reset the current active session if any, then reset the setup timeout to be sure that eventually we notify AMP to continue even if something goes wrong

    Returns void

resolveSrcObj

  • resolveSrcObj(srcObj: any): Promise<Object>

resolveTicketPromise

  • resolveTicketPromise(ticketUrl: string): Promise<HiveSessionInternal>
  • Attempt to resolve a ticket through any of the available techs

    In a loop through all the tech, one at the time:

    • First checks if the tech is available
    • Then checks if the tech needs a Reporting Instance (verified ticket)
    • Then tries to initialize a session with that tech
    • If successful, resolve the promise with the initialized HiveSession

    In case no tech can resolve the Session, an the Promise will fail with a HiveTechError

    Parameters

    • ticketUrl: string

    Returns Promise<HiveSessionInternal>

setStatusCode

  • setStatusCode(mainStatusCode: number, tech?: HiveTech): void
  • set the status code according to the MainStatusCode and the tech used the hexadecimal code is structured like this: 0x 0 0 0 0 0 0 0 0 7 6 5 4 3 2 1 0 The 7th position defines the overall status, specified by MainStatusCode The positions from the 6th to the 0th define which Tech is active. The Techs enumeration is used in order to calculate which position refers to which tech.

    Parameters

    • mainStatusCode: number
    • Optional tech: HiveTech

      (optional, used only when the MainStatusCode is OK)

    Returns void

startPeriodicFeedback

  • startPeriodicFeedback(): void
  • Returns void

startSdnLogic

  • startSdnLogic(): void

stopPeriodicFeedback

  • stopPeriodicFeedback(): void
  • Returns void

triggerHiveSessionError

  • triggerHiveSessionError(): void

updateFlashBytesLoaded

  • updateFlashBytesLoaded(): void

updatePlayerInfo

  • updatePlayerInfo(ri: ReportingInstance): void
  • Parameters

    • ri: ReportingInstance

    Returns void

updateSourceList

  • updateSourceList(): void
  • attempt to update the source list, returns true if successful. First check if hive is included in the sdnList of the first source element. If it is, reset the local hive session and check with hive for other concurrent sessions. If all is good, try to resolve the ticket in every source element, replacing the src url.

    If at least one source url has been resolved, apply the modified list and activate the sdn plugin. Finally notify AMP.

    Returns void

Variables

HIVE_COMM_JAVA

HIVE_COMM_JAVA: boolean

HIVE_COMM_JS

HIVE_COMM_JS: boolean

Functions

genSDN

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method

Generated using TypeDoc