BluetoothAudioPlugin.md

Bluetooth Audio Plugin

Version: 1.0

Status: ⚫⚪⚪

BluetoothAudio plugin for Thunder framework.

Table of Contents

• Introduction
• Description
• Configuration
• Interfaces
• Methods
• Properties
• Notifications

Introduction

Scope

This document describes purpose and functionality of the BluetoothAudio 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
BR/EDR	Basic Rate/Enhanced Data Rate
HTTP	Hypertext Transfer Protocol
JSON	JavaScript Object Notation; a data interchange format
JSON-RPC	A remote procedure call protocol encoded in JSON
LC-SBC	Low-Complexity SubBand Coding

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

Term	Description
bitpool	A parameter to the LC-SBC codec that changes the encoding bitrate; the higher it is the higher the bitrate and thus the audio quality
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 Bluetooth Audio Sink plugin enables audio streaming to Bluetooth audio sink devices. The plugin is sink a from the host device stack perspective; in Bluetooth topology the host device becomes in fact an audio source. The plugin requires a Bluetooth controller service that will provide Bluetooth BR/EDR scanning, pairing and connection functionality; typically this is fulfiled by the BluetoothControl plugin.

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: BluetoothAudio)
classname	string	Class name: BluetoothAudio
locator	string	Library name: libThunderBluetoothAudio.so
startmode	string	Determines if the plugin shall be started automatically along with the framework
controller	string	(optional) Callsign of the Bluetooth controller service (typically BluetoothControl)
server	object	(optional) BluetoothAudio server configuration
server?.interface	number	(optional) Bluetooth interface to listen to for incomming connections
server?.inactivitytimeout	number	(optional) Timeout to drop inactive connections (in ms)
server?.psm	number	(optional) Port to listen to for incomming conections (typically 25)
sink	object	(optional) BluetoothAudio sink configuration
sink.codecs	object	Codec settings
sink.codecs.LC-SBC	object	Settings for the LC-SBC codec
sink.codecs.LC-SBC?.preset	string	(optional) Predefined audio quality setting (must be one of the following: Compatible, LQ, MQ, HQ, XQ)
sink.codecs.LC-SBC?.bitpool	number	(optional) Custom audio quality based on bitpool value (used when preset is not specified)
sink.codecs.LC-SBC?.channelmode	string	(optional) Channel mode for custom audio quality (used when preset is not specified) (must be one of the following: Mono, Stereo, JointStereo, DualChannel)
source	object	(optional) BluetoothAudio source configuration
source.codecs	object	Codec settings
source.codecs?.LC-SBC	object	(optional) Settings for the LC-SBC codec
source.codecs?.LC-SBC.maxbitpool	number	Maximum accepted bitpool value

Interfaces

This plugin implements the following interfaces:

• IBluetoothAudio::ISink (IBluetoothAudio.h) (version 1.0.0) (compliant format)
• IBluetoothAudio::ISource (IBluetoothAudio.h) (version 1.0.0) (compliant format)

Methods

The following methods are provided by the BluetoothAudio plugin:

BluetoothAudio Sink interface methods:

Method	Description
sink::assign	Assigns a Bluetooth sink device for audio playback
sink::revoke	Revokes a Bluetooth sink device from audio playback

sink::assign ^method

Assigns a Bluetooth sink device for audio playback.

Parameters

Name	Type	Description
params	object
params.address	string	Address of the bluetooth device to assign

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
	ERROR_BAD_REQUEST	Device address value is invalid
	ERROR_ALREADY_CONNECTED	A sink device is already assigned

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::assign",
  "params": {
    "address": "..."
  }
}

Response

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

sink::revoke ^method

Revokes a Bluetooth sink device from audio playback.

Parameters

This method takes no parameters.

Result

Name	Type	Description
result	null	Always null

Errors

Code	Message	Description
	ERROR_ALREADY_RELEASED	No device is currently assigned as sink

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::revoke"
}

Response

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

Properties

The following properties are provided by the BluetoothAudio plugin:

BluetoothAudio Sink interface properties:

Property	Description
sink::state RO	Current state o the audio sink device
sink::device RO	Bluetooth address of the audio sink device
sink::type RO	Type of the audio sink device
sink::latency	Latency of the audio sink device
sink::supportedcodecs RO	Audio codecs supported by the audio sink device
sink::supporteddrms RO	DRM schemes supported by the audio sink device
sink::codec RO	Properites of the currently used audio codec
sink::drm RO	Properites of the currently used DRM scheme
sink::stream RO	v of the currently transmitted audio stream

BluetoothAudio Source interface properties:

Property	Description
source::state RO	Current state of the source device
source::device RO	Bluetooth address of the source device
source::type RO	Type of the audio source device
source::codec RO	Properites of the currently used codec
source::drm RO	Properties of the currently used DRM scheme
source::stream RO	Properites of the currently transmitted audio stream

sink::state ^property

Provides access to the current state o the audio sink device.

This property is read-only.

Value

Result

Name	Type	Description
result	string	Current state o the audio sink device (must be one of the following: Unassigned, Disconnected, Connecting, Connected, ConnectedBad, ConnectedRestricted, Ready, Streaming)

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::state"
}

Get Response

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

sink::device ^property

Provides access to the bluetooth address of the audio sink device.

This property is read-only.

Value

Result

Name	Type	Description
result	string	Bluetooth address of the audio sink device

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	The sink device currently is not assigned

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::device"
}

Get Response

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

sink::type ^property

Provides access to the type of the audio sink device.

This property is read-only.

Value

Result

Name	Type	Description
result	string	Type of the audio sink device (must be one of the following: Unknown, Headphone, Speaker, Recorder, Amplifier)

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	The sink device currently is not connected

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::type"
}

Get Response

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

sink::latency ^property

Provides access to the latency of the audio sink device.

Value

Name	Type	Description
(property)	object	Latency of the audio sink device
(property).value	integer	Audio latency in milliseconds

Result

Name	Type	Description
result	integer

Errors

Code	Message	Description
	ERROR_BAD_REQUEST	Latency value is invalid

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::latency"
}

Get Response

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

Set Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::latency",
  "params": {
    "value": 20
  }
}

Set Response

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

sink::supportedcodecs ^property

Provides access to the audio codecs supported by the audio sink device.

This property is read-only.

Value

Result

Name	Type	Description
result	array	Audio codecs supported by the audio sink device
result[#]	string	(must be one of the following: LC-SBC)

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	The sink device currently is not connected

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::supportedcodecs"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": [
    "LC-SBC"
  ]
}

sink::supporteddrms ^property

Provides access to the DRM schemes supported by the audio sink device.

This property is read-only.

Value

Result

Name	Type	Description
result	array	DRM schemes supported by the audio sink device
result[#]	string	(must be one of the following: DTCP, SCMS-T)

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	The sink device currently is not connected

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::supporteddrms"
}

Get Response

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

sink::codec ^property

Provides access to the properites of the currently used audio codec.

This property is read-only.

Value

Result

Name	Type	Description
result	object	Properites of the currently used audio codec
result.codec	string	Audio codec used (must be one of the following: LC-SBC)
result.settings	opaque object	Codec-specific audio quality preset, compression profile, etc

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	The sink device currently is not configured

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::codec"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "codec": "LC-SBC",
    "settings": {}
  }
}

sink::drm ^property

Provides access to the properites of the currently used DRM scheme.

This property is read-only.

Value

Result

Name	Type	Description
result	object	Properites of the currently used DRM scheme
result.drm	string	Content protection scheme used (must be one of the following: DTCP, SCMS-T)
result.settings	opaque object	DRM-specific content protection level, encoding rules, etc

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	The sink device currently is not connected or not yet configured

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::drm"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "drm": "DTCP",
    "settings": {}
  }
}

sink::stream ^property

Provides access to the v of the currently transmitted audio stream.

This property is read-only.

Value

Result

Name	Type	Description
result	object	v of the currently transmitted audio stream
result.samplerate	integer	Sample rate in Hz
result.bitrate	integer	Target bitrate in bits per second (eg. 320000)
result.channels	integer	Number of audio channels
result.resolution	integer	Sampling resolution in bits per sample
result.isresampled	boolean	Indicates if the source stream is being resampled by the stack to match sink capabilities

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	The sink device currently is not connected or not yet configured

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.sink::stream"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "samplerate": 44100,
    "bitrate": 0,
    "channels": 2,
    "resolution": 16,
    "isresampled": false
  }
}

source::state ^property

Provides access to the current state of the source device.

This property is read-only.

Value

Result

Name	Type	Description
result	string	Current state of the source device (must be one of the following: Unassigned, Disconnected, Connecting, Connected, ConnectedBad, ConnectedRestricted, Ready, Streaming)

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.source::state"
}

Get Response

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

source::device ^property

Provides access to the bluetooth address of the source device.

This property is read-only.

Value

Result

Name	Type	Description
result	string	Bluetooth address of the source device

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	No source device is currently connected

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.source::device"
}

Get Response

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

source::type ^property

Provides access to the type of the audio source device.

This property is read-only.

Value

Result

Name	Type	Description
result	string	Type of the audio source device (must be one of the following: Unknown, Player, Microphone, Tuner, Mixer)

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	No source device is currently connected

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.source::type"
}

Get Response

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

source::codec ^property

Provides access to the properites of the currently used codec.

This property is read-only.

Value

Result

Name	Type	Description
result	object	Properites of the currently used codec
result.codec	string	Audio codec used (must be one of the following: LC-SBC)
result.settings	opaque object	Codec-specific audio quality preset, compression profile, etc

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	No source device is not connected or sink is not yet configured

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.source::codec"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "codec": "LC-SBC",
    "settings": {}
  }
}

source::drm ^property

Provides access to the properties of the currently used DRM scheme.

This property is read-only.

Value

Result

Name	Type	Description
result	object	Properties of the currently used DRM scheme
result.drm	string	Content protection scheme used (must be one of the following: DTCP, SCMS-T)
result.settings	opaque object	DRM-specific content protection level, encoding rules, etc

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	No source device is connected or sink is not yet configured

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.source::drm"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "drm": "DTCP",
    "settings": {}
  }
}

source::stream ^property

Provides access to the properites of the currently transmitted audio stream.

This property is read-only.

Value

Result

Name	Type	Description
result	object	Properites of the currently transmitted audio stream
result.samplerate	integer	Sample rate in Hz
result.bitrate	integer	Target bitrate in bits per second (eg. 320000)
result.channels	integer	Number of audio channels
result.resolution	integer	Sampling resolution in bits per sample
result.isresampled	boolean	Indicates if the source stream is being resampled by the stack to match sink capabilities

Errors

Code	Message	Description
	ERROR_ILLEGAL_STATE	No source device is connected or sink is not yet configured

Example

Get Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "BluetoothAudio.1.source::stream"
}

Get Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "samplerate": 44100,
    "bitrate": 0,
    "channels": 2,
    "resolution": 16,
    "isresampled": false
  }
}

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 BluetoothAudio plugin:

BluetoothAudio Sink interface events:

Event	Description
sink::statechanged	Signals audio sink state change

BluetoothAudio Source interface events:

Event	Description
source::statechanged	Signals audio source state change

sink::statechanged ^event

Signals audio sink state change.

Parameters

Name	Type	Description
params	object
params.state	string	(must be one of the following: Unassigned, Disconnected, Connecting, Connected, ConnectedBad, ConnectedRestricted, Ready, Streaming)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.sink::statechanged",
  "params": {
    "state": "Unassigned"
  }
}

source::statechanged ^event

Signals audio source state change.

Parameters

Name	Type	Description
params	object
params.state	string	(must be one of the following: Unassigned, Disconnected, Connecting, Connected, ConnectedBad, ConnectedRestricted, Ready, Streaming)

Example

{
  "jsonrpc": "2.0",
  "method": "client.events.1.source::statechanged",
  "params": {
    "state": "Unassigned"
  }
}