Integrate with 3rd party Software (REST Interface)

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

1. NATS broker needs to be up & running

let's assume you run the nats-server on your local machine

$ nats-server

2. Start a remoteAudio server

$ ./remoteAudio server nats -u=localhost -Y=TS480

3. Start another remoteAudio server (not strictly necessary)

$ ./remoteAudio server nats -u=localhost -Y=FT950

4. 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
}