Skip to content

Latest commit

 

History

History
1138 lines (829 loc) · 23.5 KB

StreamerPlugin.md

File metadata and controls

1138 lines (829 loc) · 23.5 KB
Raw

Streamer Plugin

Version: 1.0

Status: ⚫⚪⚪

Streamer plugin for Thunder framework.

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the Streamer plugin. It includes detailed specification about its configuration, methods and properties as well as sent notifications.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
Thunder Thunder API Reference

Description

.

The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].

Configuration

The table below lists configuration options of the plugin.

Name Type Description
callsign string Plugin instance name (default: Streamer)
classname string Class name: Streamer
locator string Library name: libThunderStreamer.so
startmode string Determines if the plugin shall be started automatically along with the framework

Interfaces

This plugin implements the following interfaces:

Methods

The following methods are provided by the Streamer plugin:

Streamer interface methods:

Method Description
create Creates a stream instance
destroy Destroys a stream instance
load Loads a source into a stream
attach Attaches a decoder to the streamer
detach Detaches a decoder from the streamer

create method

Creates a stream instance.

Parameters

Name Type Description
params object
params.type string Stream type (must be one of the following: undefined, cable, handheld, satellite, terrestrial, dab, rf, unicast, multicast, ip)

Result

Name Type Description
result number Stream ID

Errors

Code Message Description
30 ERROR_BAD_REQUEST Invalid stream type given
2 ERROR_UNAVAILABLE Fronted of the selected stream type is not available

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.create",
  "params": {
    "type": "cable"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 0
}

destroy method

Destroys a stream instance.

Parameters

Name Type Description
params object
params.id number Stream ID

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.destroy",
  "params": {
    "id": 0
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

load method

Loads a source into a stream.

Also see: statechange

Parameters

Name Type Description
params object
params.id number Stream ID
params.location string Location of the source to load

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
15 ERROR_INCORRECT_URL Invalid location given
1 ERROR_GENERAL Undefined loading error
5 ERROR_ILLEGAL_STATE Stream is not in a valid state

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.load",
  "params": {
    "id": 0,
    "location": "http://example.com/sample.m3u8"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

attach method

Attaches a decoder to the streamer.

Parameters

Name Type Description
params object
params.id number Stream ID

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
12 ERROR_INPROGRESS Decoder already attached
5 ERROR_ILLEGAL_STATE Stream is not in a valid state
2 ERROR_UNAVAILABLE No free decoders available

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.attach",
  "params": {
    "id": 0
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

detach method

Detaches a decoder from the streamer.

Parameters

Name Type Description
params object
params.id number Stream ID

Result

Name Type Description
result null Always null

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
5 ERROR_ILLEGAL_STATE Stream is not in a valid state or decoder not attached
12 ERROR_INPROGRESS Decoder is in use

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.detach",
  "params": {
    "id": 0
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

Properties

The following properties are provided by the Streamer plugin:

Streamer interface properties:

Property Description
speed Playback speed
position Stream position
window Stream playback window
speeds RO Speeds supported by the stream player
streams RO All created stream instance IDs
type RO Type of a stream
drm RO DRM type associated with a stream
state RO Current state of a stream
metadata RO Metadata associated with the stream
error RO Most recent error code
elements RO Stream elements

speed property

Provides access to the playback speed.

Description

Speed (in percentage)

Also see: statechange

Value

Name Type Description
(property) number Speed percentage; e.g.: 0 - pause, 100 - normal playback, -100 - rewind, -200 - reverse at twice the normal speed, 50 - forward at half speed, etc. Must be one of the speeds supported by the player

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.speed@0.

Result

Name Type Description
result number Speed percentage; e.g.: 0 - pause, 100 - normal playback, -100 - rewind, -200 - reverse at twice the normal speed, 50 - forward at half speed, etc. Must be one of the speeds supported by the player

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
5 ERROR_ILLEGAL_STATE Player is not in a valid state or decoder not attached

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.speed@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 100
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.speed@0",
  "params": 100
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

position property

Provides access to the stream position.

Value

Name Type Description
(property) number Position (in milliseconds)

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.position@0.

Result

Name Type Description
result number Position (in milliseconds)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
5 ERROR_ILLEGAL_STATE Player is not in a valid state or decoder not attached

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.position@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 60000
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.position@0",
  "params": 60000
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

window property

Provides access to the stream playback window.

Value

Name Type Description
(property) object Geometry of the window
(property).x number Horizontal position of the window (in pixels)
(property).y number Vertical position of the window (in pixels)
(property).width number Width of the window (in pixels)
(property).height number Height of the window (in pixels)

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.window@0.

Result

Name Type Description
result object Geometry of the window
result.x number Horizontal position of the window (in pixels)
result.y number Vertical position of the window (in pixels)
result.width number Width of the window (in pixels)
result.height number Height of the window (in pixels)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
5 ERROR_ILLEGAL_STATE Player is not in a valid state or decoder not attached

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.window@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "x": 0,
    "y": 0,
    "width": 1080,
    "height": 720
  }
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.window@0",
  "params": {
    "x": 0,
    "y": 0,
    "width": 1080,
    "height": 720
  }
}

Set Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": "null"
}

speeds property

Provides access to the speeds supported by the stream player.

This property is read-only.

Value

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.speeds@0.

Result

Name Type Description
result array Supported speeds (in percentage)
result[#] integer (speeds in percentage)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
5 ERROR_ILLEGAL_STATE Player is not in a valid state or decoder not attached

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.speeds@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    0,
    100,
    -100,
    200,
    -200,
    400,
    -400
  ]
}

streams property

Provides access to the all created stream instance IDs.

This property is read-only.

Value

Result

Name Type Description
result array Stream IDs
result[#] number (a stream ID)

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.streams"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    0,
    1,
    2,
    3
  ]
}

type property

Provides access to the type of a stream.

This property is read-only.

Value

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.type@0.

Result

Name Type Description
result string Stream type (must be one of the following: undefined, cable, handheld, satellite, terrestrial, dab, rf, unicast, multicast, ip)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.type@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "cable"
}

drm property

Provides access to the DRM type associated with a stream.

This property is read-only.

Also see: drmchange

Value

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.drm@0.

Result

Name Type Description
result string DRM used (must be one of the following: none, clearkey, playready, widevine, unknown)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.drm@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "clearkey"
}

state property

Provides access to the current state of a stream.

This property is read-only.

Also see: statechange

Value

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.state@0.

Result

Name Type Description
result string Stream state (must be one of the following: idle, loading, prepared, controlled, error)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.state@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "controlled"
}

metadata property

Provides access to the metadata associated with the stream.

This property is read-only.

Value

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.metadata@0.

Result

Name Type Description
result string Custom implementation-specific metadata

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.metadata@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "..."
}

error property

Provides access to the most recent error code.

This property is read-only.

Value

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.error@0.

Result

Name Type Description
result number Custom implementation-specific error code value

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.error@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 0
}

elements property

Provides access to the stream elements.

This property is read-only.

Value

The stream id argument shall be passed as the index to the property, e.g. Streamer.1.elements@0.

Result

Name Type Description
result array List of stream elements
result[#] object Stream element
result[#].type string Stream element type (must be one of the following: video, audio, subtitles, teletext, data)

Errors

Code Message Description
22 ERROR_UNKNOWN_KEY Unknown stream ID given
2 ERROR_UNAVAILABLE Stream elements retrieval not supported

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.elements@0"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    {
      "type": "video"
    }
  ]
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the Streamer plugin:

Streamer interface events:

Event Description
statechange Notifies of stream state change
timeupdate Notifies of stream position change
stream Notifies of a custom stream incident
player Notifies of a custom player incident
drm Notifies of a custom DRM-related incident

statechange event

Notifies of stream state change.

Parameters

Name Type Description
params object
params.state string Stream state (must be one of the following: idle, loading, prepared, controlled, error)

The Stream ID argument shall be passed within the designator, e.g. 0.client.events.1.

Example

{
  "jsonrpc": "2.0",
  "method": "0.client.events.1.statechange",
  "params": {
    "state": "controlled"
  }
}

timeupdate event

Notifies of stream position change. This event is fired every second to indicate the current stream position. It does not fire if the stream is paused (i.e. speed is set to 0).

Parameters

Name Type Description
params object
params.time number Stream position in miliseconds

The Stream ID argument shall be passed within the designator, e.g. 0.client.events.1.

Example

{
  "jsonrpc": "2.0",
  "method": "0.client.events.1.timeupdate",
  "params": {
    "time": 30000
  }
}

stream event

Notifies of a custom stream incident.

Parameters

Name Type Description
params object
params.code number Implementation-specific incident code

The Stream ID argument shall be passed within the designator, e.g. 0.client.events.1.

Example

{
  "jsonrpc": "2.0",
  "method": "0.client.events.1.stream",
  "params": {
    "code": 1
  }
}

player event

Notifies of a custom player incident.

Parameters

Name Type Description
params object
params.code number Implementation-specific incident code

The Stream ID argument shall be passed within the designator, e.g. 0.client.events.1.

Example

{
  "jsonrpc": "2.0",
  "method": "0.client.events.1.player",
  "params": {
    "code": 1
  }
}

drm event

Notifies of a custom DRM-related incident.

Parameters

Name Type Description
params object
params.code number Implementation-specific incident code

The Stream ID argument shall be passed within the designator, e.g. 0.client.events.1.

Example

{
  "jsonrpc": "2.0",
  "method": "0.client.events.1.drm",
  "params": {
    "code": 1
  }
}