Skip to content

Latest commit

 

History

History
1298 lines (944 loc) · 27.5 KB

StreamerPlugin.md

File metadata and controls

1298 lines (944 loc) · 27.5 KB

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 M/O Description
callsign string mandatory Plugin instance name (default: Streamer)
classname string mandatory Class name: Streamer
locator string mandatory Library name: libThunderStreamer.so
startmode string mandatory Determines in which state the plugin should be moved to at startup of 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 M/O Description
params object mandatory ...
params.type string mandatory Stream type (must be one of the following: cable, dab, handheld, ip, multicast, rf, satellite, terrestrial, undefined, unicast)

Result

Name Type M/O Description
result integer mandatory Stream ID

Errors

Message Description
ERROR_BAD_REQUEST Invalid stream type given
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 M/O Description
params object mandatory ...
params.id integer mandatory Stream ID

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
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 M/O Description
params object mandatory ...
params.id integer mandatory Stream ID
params.location string mandatory Location of the source to load

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
ERROR_INCORRECT_URL Invalid location given
ERROR_GENERAL Undefined loading error
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 M/O Description
params object mandatory ...
params.id integer mandatory Stream ID

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
ERROR_INPROGRESS Decoder already attached
ERROR_ILLEGAL_STATE Stream is not in a valid state
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 M/O Description
params object mandatory ...
params.id integer mandatory Stream ID

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
ERROR_ILLEGAL_STATE Stream is not in a valid state or decoder not attached
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 R/W Description
speed read/write Playback speed
position read/write Stream position
window read/write Stream playback window
speeds read-only Speeds supported by the stream player
streams read-only All created stream instance IDs
type read-only Type of a stream
drm read-only DRM type associated with a stream
state read-only Current state of a stream
metadata read-only Metadata associated with the stream
error read-only Most recent error code
elements read-only Stream elements

speed property

Provides access to the playback speed.

Description

Speed (in percentage)

Also see: statechange

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.speed@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Name Type M/O Description
(property) integer mandatory 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

Result

Name Type M/O Description
result integer mandatory 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

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
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.

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.position@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Name Type M/O Description
(property) integer mandatory Position (in milliseconds)

Result

Name Type M/O Description
result integer mandatory Position (in milliseconds)

Errors

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
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.

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.window@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Name Type M/O Description
(property) object mandatory Geometry of the window
(property).x integer mandatory Horizontal position of the window (in pixels)
(property).y integer mandatory Vertical position of the window (in pixels)
(property).width integer mandatory Width of the window (in pixels)
(property).height integer mandatory Height of the window (in pixels)

Result

Name Type M/O Description
result object mandatory Geometry of the window
result.x integer mandatory Horizontal position of the window (in pixels)
result.y integer mandatory Vertical position of the window (in pixels)
result.width integer mandatory Width of the window (in pixels)
result.height integer mandatory Height of the window (in pixels)

Errors

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
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.

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.speeds@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Result

Name Type M/O Description
result array mandatory Supported speeds (in percentage)
result[#] integer mandatory (speeds in percentage)

Errors

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
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 M/O Description
result array mandatory Stream IDs
result[#] integer mandatory (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.

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.type@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Result

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

Errors

Message Description
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

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.drm@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Result

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

Errors

Message Description
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

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.state@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Result

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

Errors

Message Description
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.

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.metadata@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Result

Name Type M/O Description
result string mandatory Custom implementation-specific metadata

Errors

Message Description
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.

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.error@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Result

Name Type M/O Description
result integer mandatory Custom implementation-specific error code value

Errors

Message Description
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.

The stream id parameter shall be passed as the index to the property, e.g. Streamer.1.elements@<stream-id>.

Index

Name Type M/O Description
stream-id string mandatory ...

Value

Result

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

Errors

Message Description
ERROR_UNKNOWN_KEY Unknown stream ID given
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:

Notification 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 notification

Notifies of stream state change.

Parameters

The Stream ID parameter shall be passed within the client ID during registration, e.g. 0.myid

Notification Parameters

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

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.register",
  "params": {
    "event": "statechange",
    "id": "0.myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "0.myid.statechange",
  "params": {
    "state": "controlled"
  }
}

The Stream ID parameter is passed within the designator, e.g. 0.myid.statechange.

timeupdate notification

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

The Stream ID parameter shall be passed within the client ID during registration, e.g. 0.myid

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.time integer mandatory Stream position in miliseconds

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.register",
  "params": {
    "event": "timeupdate",
    "id": "0.myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "0.myid.timeupdate",
  "params": {
    "time": 30000
  }
}

The Stream ID parameter is passed within the designator, e.g. 0.myid.timeupdate.

stream notification

Notifies of a custom stream incident.

Parameters

The Stream ID parameter shall be passed within the client ID during registration, e.g. 0.myid

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.code integer mandatory Implementation-specific incident code

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.register",
  "params": {
    "event": "stream",
    "id": "0.myid"
  }
}

Notification

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

The Stream ID parameter is passed within the designator, e.g. 0.myid.stream.

player notification

Notifies of a custom player incident.

Parameters

The Stream ID parameter shall be passed within the client ID during registration, e.g. 0.myid

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.code integer mandatory Implementation-specific incident code

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.register",
  "params": {
    "event": "player",
    "id": "0.myid"
  }
}

Notification

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

The Stream ID parameter is passed within the designator, e.g. 0.myid.player.

drm notification

Notifies of a custom DRM-related incident.

Parameters

The Stream ID parameter shall be passed within the client ID during registration, e.g. 0.myid

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.code integer mandatory Implementation-specific incident code

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "Streamer.1.register",
  "params": {
    "event": "drm",
    "id": "0.myid"
  }
}

Notification

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

The Stream ID parameter is passed within the designator, e.g. 0.myid.drm.