Jamulus JSON-RPC Server Documentation
March 3, 2026 · View on GitHub
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.
Wire protocol
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.
Connect to a JSON-RPC server
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)
Example
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"}}
Method reference
jamulus/apiAuth
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 |
jamulus/getMode
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). |
jamulus/getVersion
Returns Jamulus version.
Parameters:
| Name | Type | Description |
|---|---|---|
| params | object | No parameters (empty object). |
Results:
| Name | Type | Description |
|---|---|---|
| result.version | string | The Jamulus version. |
jamulusclient/getChannelInfo
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.country | string | The musician’s country. |
| result.city | string | The musician’s city. |
| result.instrumentId | number | The musician’s instrument ID (see CInstPictures::GetTable). |
| result.instrument | string | The musician’s instrument. |
| result.skillLevel | string | Your skill level (beginner, intermediate, expert, or null). |
jamulusclient/getClientInfo
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. |
jamulusclient/getClientList
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. |
jamulusclient/getMidiDevices
Returns a list of available MIDI input devices.
Parameters:
| Name | Type | Description |
|---|---|---|
| params | object | No parameters (empty object). |
Results:
| Name | Type | Description |
|---|---|---|
| result | array | Array of MIDI device name strings. |
jamulusclient/getMidiSettings
Returns all MIDI controller settings.
Parameters:
| Name | Type | Description |
|---|---|---|
| params | object | No parameters (empty object). |
Results:
| Name | Type | Description |
|---|---|---|
| result | object | MIDI settings object. |
jamulusclient/pollServerList
Request list of servers in a directory.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.directory | string | Socket address of directory to query. Example: anygenre1.jamulus.io:22124 |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | "ok" or "error" if bad arguments. |
jamulusclient/sendChatText
Sends a chat text message.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.chatText | string | The chat text message. |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | Always "ok". |
jamulusclient/setFaderLevel
Sets the fader level. Example: {"id":1,"jsonrpc":"2.0","method":"jamulusclient/setFaderLevel","params":{"channelIndex": 0,"level": 50}}.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.channelIndex | number | The channel index of the fader to be set. |
| params.level | number | The fader level in range 0..100. |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | Always "ok". |
jamulusclient/setMidiSettings
Sets one or more MIDI controller settings.
Parameters:
| Name | Type | Description |
|---|---|---|
| params | object | Any subset of MIDI settings fields to set. |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | Always "ok". |
jamulusclient/setName
Sets your name.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.name | string | The new name. |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | Always "ok". |
jamulusclient/setSkillLevel
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". |
jamulusserver/getClients
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. |
jamulusserver/getRecorderStatus
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. |
jamulusserver/getServerProfile
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.directoryType | string | The directory type as a string (see EDirectoryType and SerializeDirectoryType). |
| result.directoryAddress | string | The string used to look up the directory address (only assume valid if directoryType is "custom" and registrationStatus is "registered"). |
| 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). |
jamulusserver/restartRecording
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. |
jamulusserver/setDirectory
Set the directory type and, for custom, the directory address.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.directoryType | string | The directory type as a string (see EDirectoryType and DeserializeDirectoryType). |
| [params.directoryAddress] | string | (optional) The directory address, required if directoryType is "custom". |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | Always "ok". |
jamulusserver/setRecordingDirectory
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. |
jamulusserver/setServerName
Sets the server name.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.serverName | string | The new server name. |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | Always "ok". |
jamulusserver/setWelcomeMessage
Sets the server welcome message.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.welcomeMessage | string | The new welcome message. |
Results:
| Name | Type | Description |
|---|---|---|
| result | string | Always "ok". |
jamulusserver/startRecording
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. |
jamulusserver/stopRecording
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. |
Notification reference
jamulusclient/channelLevelListReceived
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. |
jamulusclient/chatTextReceived
Emitted when a chat text is received.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.chatText | string | The chat text. |
jamulusclient/clientListReceived
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[*].country | string | The musician’s country. |
| params.clients[*].city | string | The musician’s city. |
| params.clients[*].instrumentId | number | The musician’s instrument ID (see CInstPictures::GetTable). |
| params.clients[*].instrument | string | The musician’s instrument. |
jamulusclient/connected
Emitted when the client is connected to the server.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.id | number | The channel ID assigned to the client. |
jamulusclient/disconnected
Emitted when the client is disconnected from the server.
Parameters:
| Name | Type | Description |
|---|---|---|
| params | object | No parameters (empty object). |
jamulusclient/recorderState
Emitted when the client is connected to a server whose recorder state changes.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.state | number | The recorder state. |
jamulusclient/serverInfoReceived
Emitted when a server info is received.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.address | string | The server socket address. |
| params.pingtime | number | The round-trip ping time, in milliseconds. |
| params.numClients | number | The number of clients connected to the server. |
jamulusclient/serverListReceived
Emitted when the server list is received.
Parameters:
| Name | Type | Description |
|---|---|---|
| params.servers | array | The server list. |
| params.servers[*].address | string | Socket address (ip_address:port). |
| params.servers[*].name | string | Server name. |
| params.servers[*].countryId | number | Server country ID (see QLocale::Country). |
| params.servers[*].country | string | Server country. |
| params.servers[*].city | string | Server city. |