Skip to content

AudioStream API

Version: 1.0.0

Status: ⚫⚪⚪

AudioStream interface for Thunder framework.

(Defined with IAudioStream in IVoiceHandler.h)

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the AudioStream interface (version 1.0.0). It includes detailed specification about its properties provided and notifications sent.

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

AudioStream JSON-RPC interface.

This interface uses legacy lowercase naming convention. With the next major release the naming convention will change to camelCase.

Properties

The following properties are provided by the AudioStream interface:

AudioStream interface properties:

Property R/W Description
name read-only Name of the stream
state read-only Current state of the stream
capabilities read-only List of codecs supported by the stream
audioprofile read/write Preferred profile of the stream
time read-only Stream position
speed read/write Stream speed

name property

Provides access to the name of the stream.

This property is read-only.

Value

Name Type M/O Description
(property) string mandatory Name of the stream

Errors

Message Description
ERROR_ILLEGAL_STATE The stream is not ready for this operation

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.name"
}

Get Response

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

state property

Provides access to the current state of the stream.

This property is read-only.

Value

Name Type M/O Description
(property) string mandatory Current state of the stream (must be one of the following: Idle, Started, Unavailable)

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.state"
}

Get Response

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

capabilities property

Provides access to the list of codecs supported by the stream.

This property is read-only.

Value

Name Type M/O Description
(property) array mandatory List of codecs supported by the stream
(property)[#] string mandatory ... (must be one of the following: IMA-ADPCM, PCM)

Errors

Message Description
ERROR_ILLEGAL_STATE The stream is not ready for this operation

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.capabilities"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    "IMA-ADPCM"
  ]
}

audioprofile property

Provides access to the preferred profile of the stream.

Value

Name Type M/O Description
(property) object mandatory Preferred profile of the stream
(property).value object mandatory ...
(property).value.codec string mandatory Compression method (PCM: uncompressed) (must be one of the following: IMA-ADPCM, PCM)
(property).value?.codecparams opaque object optional Additional parameters for codec
(property).value.channels integer mandatory Number of audio channels
(property).value.resolution integer mandatory Sample resultion in bits
(property).value.samplerate integer mandatory Sample rate in hertz
(property).value?.bitrate integer optional Data rate of the compressed stream in bits per second
Name Type M/O Description
(property) object mandatory Preferred profile of the stream
(property).codec string mandatory Compression method (PCM: uncompressed) (must be one of the following: IMA-ADPCM, PCM)
(property)?.codecparams opaque object optional Additional parameters for codec
(property).channels integer mandatory Number of audio channels
(property).resolution integer mandatory Sample resultion in bits
(property).samplerate integer mandatory Sample rate in hertz
(property)?.bitrate integer optional Data rate of the compressed stream in bits per second

Errors

Message Description
ERROR_NOT_SUPPORTED Profile change is not supported by this stream
ERROR_ILLEGAL_STATE The stream is not ready for this operation
ERROR_BAD_REQUEST The profile specified is invalid
ERROR_INPROGRESS Stream is started, profile will be changed for the next streaming

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.audioprofile"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "codec": "IMA-ADPCM",
    "codecparams": {},
    "channels": 1,
    "resolution": 16,
    "samplerate": 16000,
    "bitrate": 64000
  }
}

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.audioprofile",
  "params": {
    "value": {
      "codec": "IMA-ADPCM",
      "codecparams": {},
      "channels": 1,
      "resolution": 16,
      "samplerate": 16000,
      "bitrate": 64000
    }
  }
}

Set Response

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

time property

Provides access to the stream position.

This property is read-only.

Value

Name Type M/O Description
(property) integer mandatory Stream position

Errors

Message Description
ERROR_NOT_SUPPORTED Time reporting is not supported by this stream
ERROR_ILLEGAL_STATE The stream is not ready for this operation

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.time"
}

Get Response

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

speed property

Provides access to the stream speed.

Value

Name Type M/O Description
(property) object mandatory Stream speed
(property).value integer mandatory ...
Name Type M/O Description
(property) integer mandatory Stream speed

Errors

Message Description
ERROR_NOT_SUPPORTED Speed setting is not supported by this stream
ERROR_ILLEGAL_STATE The stream is not ready for this operation

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.speed"
}

Get Response

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

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.speed",
  "params": {
    "value": 0
  }
}

Set Response

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

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 AudioStream interface:

AudioStream interface events:

Notification Description
audioframe Provides audio data
audiotransmission Signals state of the stream

audioframe notification

Provides audio data.

Notification Parameters

Name Type M/O Description
params object mandatory ...
params?.seq integer optional Frame number in current transmission
params?.timestamp integer optional Timestamp of the frame
params.length integer mandatory Size of the raw data frame in bytes
params.data string (base64) mandatory Raw audio data, the format of the data is specified in the most recent audiotransmission notification

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "audioframe",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.audioframe",
  "params": {
    "seq": 1,
    "timestamp": 0,
    "length": 400,
    "data": "..."
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.audioframe.

audiotransmission notification

Signals state of the stream.

This notification may also be triggered by client registration.

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.state string mandatory New state of the stream (must be one of the following: Idle, Started, Unavailable)
params?.profile object optional Details on the format used in the stream
params?.profile.codec string mandatory Compression method (PCM: uncompressed) (must be one of the following: IMA-ADPCM, PCM)
params?.profile?.codecparams opaque object optional Additional parameters for codec
params?.profile.channels integer mandatory Number of audio channels
params?.profile.resolution integer mandatory Sample resultion in bits
params?.profile.samplerate integer mandatory Sample rate in hertz
params?.profile?.bitrate integer optional Data rate of the compressed stream in bits per second

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "audiotransmission",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.audiotransmission",
  "params": {
    "state": "Idle",
    "profile": {
      "codec": "IMA-ADPCM",
      "codecparams": {},
      "channels": 1,
      "resolution": 16,
      "samplerate": 16000,
      "bitrate": 64000
    }
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.audiotransmission.