A JSON-RPC server can be added to both Jamulus client and Jamulus server to allow programmatic access.
To add the JSON-RPC server, run Jamulus with the --jsonrpcport <port> --jsonrpcsecretfile /file/with/a/secret.txt
options.
This will start a JSON-RPC server on the specified port on the localhost.
The file referenced by --jsonrpcsecretfile
must contain a single line with a freely chosen string with at least 16 characters.
It can be generated like this:
$ openssl rand -base64 10 > /file/with/a/secret.txt
The JSON-RPC server defaults to listening on the local loopback network interface (127.0.0.1).
This can be optionally changed by using the --jsonrpcbindip <ip address>
command line option.
The JSON-RPC server is based on the JSON-RPC 2.0 protocol, using streaming newline-delimited JSON over TCP as the transport. There are three main types of messages being exchanged:
- A request from the consumer to Jamulus.
- A response from Jamulus to the consumer.
- A notification from Jamulus to the consumer.
On Linux, you can connect to a JSON-RPC server using the nc
CLI tool.
On Windows, you can download and use the ncat
CLI tool.
This snippet uses jayson to connect using Node.js:
const jayson = require("jayson/promise");
const client = new jayson.client.tcp({ host: "127.0.0.1", port: 22100 });
client.request('jamulusserver/getServerInfo', {})
.then(console.log)
.catch(console.error)
After opening a TCP connection to the JSON-RPC server, the connection must be authenticated:
{"id":1,"jsonrpc":"2.0","method":"jamulus/apiAuth","params":{"secret": "...the secret from the file in --jsonrpcsecretfile..."}}
Request must be sent as a single line of JSON-encoded data, followed by a newline character. Jamulus will send back a response in the same manner:
{"id":1,"jsonrpc":"2.0","result":"ok"}
After successful authentication, the following request can be sent:
{"id":2,"jsonrpc":"2.0","method":"jamulus/getMode","params":{}}
The request must be sent as a single line of JSON-encoded data, followed by a newline character. Jamulus will send back a response in the same manner:
{"id":2,"jsonrpc":"2.0","result":{"mode":"client"}}
Jamulus will also send notifications to the consumer:
{"jsonrpc":"2.0","method":"jamulusclient/chatTextReceived","params":{"text":"<font color=\"mediumblue\">(01:23:45 AM) <b>user</b></font> test"}}
Authenticates the connection which is a requirement for calling further methods.
Parameters:
Name | Type | Description |
---|---|---|
params.secret | string | The preshared secret key. |
Results:
Name | Type | Description |
---|---|---|
result | string | "ok" on success |
Returns the current mode, i.e. whether Jamulus is running as a server or client.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.mode | string | The current mode (server or client). |
Returns Jamulus version.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.version | string | The Jamulus version. |
Returns the client's profile information.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.id | number | The channel ID. |
result.name | string | The musician’s name. |
result.skillLevel | string | The musician’s skill level (beginner, intermediate, expert, or null). |
result.countryId | number | The musician’s country ID (see QLocale::Country). |
result.city | string | The musician’s city. |
result.instrumentId | number | The musician’s instrument ID (see CInstPictures::GetTable). |
result.skillLevel | string | Your skill level (beginner, intermediate, expert, or null). |
Returns the client information.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.connected | boolean | Whether the client is connected to the server. |
Returns the client list.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.clients | array | The client list. See jamulusclient/clientListReceived for the format. |
Sends a chat text message.
Parameters:
Name | Type | Description |
---|---|---|
params.chatText | string | The chat text message. |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "ok". |
Sets your name.
Parameters:
Name | Type | Description |
---|---|---|
params.name | string | The new name. |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "ok". |
Sets your skill level.
Parameters:
Name | Type | Description |
---|---|---|
params.skillLevel | string | The new skill level (beginner, intermediate, expert, or null). |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "ok". |
Returns the list of connected clients along with details about them.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.connections | number | The number of active connections. |
result.clients | array | The list of connected clients. |
result.clients[*].id | number | The client’s channel id. |
result.clients[*].address | string | The client’s address (ip:port). |
result.clients[*].name | string | The client’s name. |
result.clients[*].jitterBufferSize | number | The client’s jitter buffer size. |
result.clients[*].channels | number | The number of audio channels of the client. |
result.clients[*].instrumentCode | number | The id of the instrument for this channel. |
result.clients[*].city | string | The city name provided by the user for this channel. |
result.clients[*].countryName | number | The text name of the country specified by the user for this channel (see QLocale::Country). |
result.clients[*].skillLevelCode | number | The skill level id provided by the user for this channel. |
Returns the recorder state.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.initialised | boolean | True if the recorder is initialised. |
result.errorMessage | string | The recorder error message, if any. |
result.enabled | boolean | True if the recorder is enabled. |
result.recordingDirectory | string | The recorder recording directory. |
Returns the server registration profile and status.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result.name | string | The server name. |
result.city | string | The server city. |
result.countryId | number | The server country ID (see QLocale::Country). |
result.welcomeMessage | string | The server welcome message. |
result.directory | string | The directory with which this server requested registration, or blank if none. |
result.registrationStatus | string | The server registration status as string (see ESvrRegStatus and SerializeRegistrationStatus). |
Restarts the recording into a new directory.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "acknowledged". To check if the recording was restarted or if there is any error, call jamulusserver/getRecorderStatus again. |
Sets the server recording directory.
Parameters:
Name | Type | Description |
---|---|---|
params.recordingDirectory | string | The new recording directory. |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "acknowledged". To check if the directory was changed, call jamulusserver/getRecorderStatus again. |
Sets the server name.
Parameters:
Name | Type | Description |
---|---|---|
params.serverName | string | The new server name. |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "ok". |
Sets the server welcome message.
Parameters:
Name | Type | Description |
---|---|---|
params.welcomeMessage | string | The new welcome message. |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "ok". |
Starts the server recording.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "acknowledged". To check if the recording was enabled, call jamulusserver/getRecorderStatus again. |
Stops the server recording.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |
Results:
Name | Type | Description |
---|---|---|
result | string | Always "acknowledged". To check if the recording was disabled, call jamulusserver/getRecorderStatus again. |
Emitted when the channel level list is received.
Parameters:
Name | Type | Description |
---|---|---|
params.channelLevelList | array | The channel level list. Each item corresponds to the respective client retrieved from the jamulusclient/clientListReceived notification. |
params.channelLevelList[*] | number | The channel level, an integer between 0 and 9. |
Emitted when a chat text is received.
Parameters:
Name | Type | Description |
---|---|---|
params.chatText | string | The chat text. |
Emitted when the client list is received.
Parameters:
Name | Type | Description |
---|---|---|
params.clients | array | The client list. |
params.clients[*].id | number | The channel ID. |
params.clients[*].name | string | The musician’s name. |
params.clients[*].skillLevel | string | The musician’s skill level (beginner, intermediate, expert, or null). |
params.clients[*].countryId | number | The musician’s country ID (see QLocale::Country). |
params.clients[*].city | string | The musician’s city. |
params.clients[*].instrumentId | number | The musician’s instrument ID (see CInstPictures::GetTable). |
Emitted when the client is connected to the server.
Parameters:
Name | Type | Description |
---|---|---|
params.id | number | The channel ID assigned to the client. |
Emitted when the client is disconnected from the server.
Parameters:
Name | Type | Description |
---|---|---|
params | object | No parameters (empty object). |