Integrate with 3rd party Software (REST Interface) - dh1tw/remoteAudio GitHub Wiki
The remoteAudio client provides a REST interface which can be used by third-party applications to control remoteAudio. This page provides information about the associated REST endpoints and the JSON messages. As an example, we will use httpie and/or CURL to make the HTTP REST calls from the command line. For integrating remoteAudio with your application you would make these HTTP calls with an HTTP library provided by your programing language.
Prerequisites
- NATS broker needs to be up & running
let's assume you run the nats-server on your local machine
$ nats-server
- Start a remoteAudio server
$ ./remoteAudio server nats -u=localhost -Y=TS480
- Start another remoteAudio server (not strictly necessary)
$ ./remoteAudio server nats -u=localhost -Y=FT950
- Start a remoteAudio client
$ ./remoteAudio client nats -u=localhost -U=MyNatsUserName
Get a list of all available audio servers
Endpoint: /api/v1.0/servers
Method: GET
$ curl localhost:9090/api/v1.0/servers
HTTP/1.1 200 OK
Content-Length: 236
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 00:58:59 GMT
{
"audio_servers": {
"FT950": {
"index": 2,
"latency": 3,
"name": "FT950",
"rx_on": false,
"tx_user": ""
},
"TS480": {
"index": 1,
"latency": 28,
"name": "TS480",
"rx_on": false,
"tx_user": ""
}
},
"connected": false,
"rx_volume": 70,
"selected_server": "TS480",
"tx_on": false,
"tx_volume": 70
}
Get details of a particular audio server
Endpoint: /api/v1.0/server/{radio}
Method: GET
$ curl localhost:9090/api/v1.0/server/ts480
HTTP/1.1 200 OK
Content-Length: 55
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:07:56 GMT
{
"index": 1,
"latency": 23,
"name": "TS480",
"rx_on": false,
"tx_user": ""
}
Start the audio stream from the TS480
Endpoint: /api/v1.0/server/{radio}/state
Method: GET, PUT
let's tell the ts480 audio server to start streaming
$ http PUT 192.168.1.156:9090/api/v1.0/server/ts480/state on:=true
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:18:55 GMT
let's check if the server has started streaming:
$ http localhost:9090/api/v1.0/server/ts480/state
HTTP/1.1 200 OK
Content-Length: 12
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:11:52 GMT
{
"on": true
}
Select an audio server
Endpoint: /api/v1.0/server/{radio}/selected
Method: GET, PUT
curl -X PUT -d "{\"selected\":true}" "localhost:9090/api/v1.0/server/ft950/selected"
http localhost:9090/api/v1.0/server/ft950/selected
HTTP/1.1 200 OK
Content-Length: 16
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:23:00 GMT
{
"selected": true
}
get & set RX volume
Endpoint: /api/v1.0/rx/volume
Method: GET, PUT
set:
$ http PUT localhost:9090/api/v1.0/rx/volume volume:=30
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:26:02 GMT
and check (get):
$ http localhost:9090/api/v1.0/rx/volume
HTTP/1.1 200 OK
Content-Length: 14
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:24:22 GMT
{
"volume": 30
}
get & set TX volume
Endpoint: /api/v1.0/tx/volume
Method: GET, PUT
set:
$ http PUT localhost:9090/api/v1.0/tx/volume volume:=120
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:26:02 GMT
and check (get):
$ http localhost:9090/api/v1.0/tx/volume
HTTP/1.1 200 OK
Content-Length: 14
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:24:22 GMT
{
"volume": 100
}
as you can see the tx level will be set to 100%, despite we tried to set it to 120%.
Get & Set PTT (Client streams audio)
Endpoint: /api/v1.0/tx/state
Method: GET, PUT
Note: Make sure you have selected the right server to which you want to send the audio.
$ curl -X PUT -d "{\"on\":true}" "localhost:9090/api/v1.0/tx/state"
make sure our client is streaming:
$ http localhost:9090/api/v1.0/tx/state
HTTP/1.1 200 OK
Content-Length: 14
Content-Type: application/json; charset=UTF-8
Date: Sun, 17 Mar 2019 01:24:22 GMT
{
"on": true
}
Control the Voice activation (VOX) for your outgoing audio stream
Endpoint: /api/v1.0/tx/vox
Method: GET, PUT
enable the VOX and raise the threshold level to 0.2:
$ http PUT localhost:9090/api/v1.0/tx/vox vox_enabled:=true vox_threshold:="0.2"
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json; charset=UTF-8
Date: Fri, 15 Nov 2019 01:42:06 GMT
and check:
$ http localhost:9090/api/v1.0/tx/vox
HTTP/1.1 200 OK
Content-Length: 86
Content-Type: application/json; charset=UTF-8
Date: Fri, 15 Nov 2019 02:07:56 GMT
{
"vox_active": false,
"vox_enabled": true,
"vox_holdtime": 500000000,
"vox_threshold": 0.2
}