Skip to content

Latest commit

 

History

History
473 lines (296 loc) · 12.2 KB

JSON-RPC.md

File metadata and controls

473 lines (296 loc) · 12.2 KB

Jamulus JSON-RPC Server Documentation

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.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).

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/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/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.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/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[*].city string The musician’s city.
params.clients[*].instrumentId number The musician’s instrument ID (see CInstPictures::GetTable).

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).