SCLOrkChat OSC Command Reference | SuperCollider 3.13.0 Help

The following is a list of all SCLOrkChatServer and SCLOrkChatClient commands and their arguments, including some documentation around typical communication scenarios of client sign-in and sign-out, sending a broadcast message, sending a targeted message, and nickname change.

All commands are SCLOrkWire OSC commands sent to specific ports on the client and server.

Server Commands

/chatSignIn

string

name

Desired name of client. Does not have to be unique.

Upon receipt, the server will reply to the sender on receivePort with a /chatSignInComplete command, as well as informing other connected clients of the sign-in via a /chatChangeClient message.

/chatGetAllClients

Process a request to enumerate all currently signed in clients. No additional arguments besides the path are supplied.

The server will respond to the client on receivePort with a /chatSetAllClients command.

/chatSendMessage

Send a message to some or all connected clients.

label	messageType	Enumerated type of message. See Message Types section for list of types.
string	contents	The contents of the message.
int	recipientId0	First element in recipientId list. If 0, the server will broadcast message to all connected clients. Th wireMap.put(wire.targetId, wire); ere should be at least 1 element in the list. wireMap.put(wire.targetId, wire);
...	...	...
int	recipientIdN	Last element in the recipientId list.

Server will send provided message to all clients in recipient list via a /chatReceive command, or to all connected clients (save the sender) if the first element in recipient list is 0. The server will also send a /chatEcho command to the sending client.

/chatChangeName

Changes the client nickname, broadcast the change to all connected clients.

string

newName

The requested new nickname of the client.

Server will send all clients notification of the name change via /chatChangeClient.

/chatSignOut

Signs the client out from the chat server. No additional arguments supplied besides the path. Server will disconnect the client SCLOrkWire, and then send all remianing clients notification of the signout via /chatChangeClient.

Client Commands

/chatSignInComplete

Server acknowledges sign-in via /chatSignIn. The unique id of the client is provided as the Server-assigned SCLOrkWire id.

int

userId

The server-assigned unique user Id for this client.

Client should include this userId as the first argument in all subsequent server calls.

/chatSetAllClients

Server responding to /chatGetAllClients command with a list of userIds and associated names in pairs.

int	id0	The id of the first client in the list.
string	name0	The name associated with the id of the first client in the list.
...	...	...
int	idN	The id of the final client in the list.
string	nameN	The name of the final client in the list.

/chatChangeClient

Used by the server to notify the client of an update to a peer client.

label	changeType	What type of change happened to the client. See changeType enumeration values table below.
int	userId	The clientId associated with this change.
string	nickName	The nickname associated with this client.

The server will send this command to all connected clients for all client changes. Clients are expected to use these command to update their own user dictionaries.

NOTE: It's possible when a client times out that there may be a few messages from it being processed by the server, so client code should be robust against receiving messages associated with userIds that have already been removed via server command.

changeType enumeration values

\add	Clients should add a new user with provided id and name to their peer lists.
\rename	Clients should update the name associated with the provided id to the new provided name.
\remove	Clients should remove the userId from their dictionaries, the client associated with this userId has signed out normally using /chatSignOut.
\timeout	Clients should remove the userId from their dictionaries, the client associated with this userId has timed out.

/chatReceive

Used to notify clients of a new chat message sent by another client.

int	senderId	Id of sending client.
label	messageType	Enumerated type of message being sent, see /Message Types for list of supported types.
string	contents	Text contents of chat message.
int	recipientId0	Id of first intended recipient. If 0, this was a broadcast message sent to all connected clients. There needs to be at least one recipientId present.
...	...	...
int	recipientIdN	Id of the last intended recipient.

Client should process the message send by senderId. Clients will not receive /chatReceive commands for messages which they are not targeted as a recipient of.

/chatEcho

Used to notify clients of the receipt by the server of the client's last sent message.

int	senderId	Id of sending client, should always be the userId of this client.
label	messageType	Enumerated type of message being sent, see /Message Types for list of supported types.
string	contents	Text contents of chat message.
int	recipientId0	Id of first intended recipient. If 0, this was a broadcast message sent to all connected clients. There needs to be at least one recipientId present.
...	...	...
int	recipientIdN	Id of the last intended recipient.

Note that message format is identical to that of /chatReceive. Server will respond to every call to /chatSendMessage with a /chatEcho.

Message Types

This table details the currently supported values of the messageType argument included in /chatSendMessage, /chatReceive, and /chatEcho commands.

\code	The message contents are to be considered as supercollider source code.
\plain	A normal chat message, the default value.
\shout	A message requiring special emphasis in the UI.
\system	Not normally sent by the server, but used by SCLOrkChatMessage to indicate a state change in the chat system.

Example Scenarios

This section lists typical scenarios in communication between client, server, and peers. The word peer is used to describe another client signed into the same chat server.

NOTE: These are explicative examples only. Due to the nondeterministic nature of network communications some message may arrive in a different order than documented here.

Client Signs In

Recipient	Command	Description
server	/chatSignIn nickName receivePort	Client sends initial nickname and the port it will receive commands from the server. Client's IP address is inferred by the server from the underlying UDP packet.
client	/chatSignInComplete userId	Server responds to client with a unique userId, which client should associated with all future commands sent to the server.
server	/chatGetAllClients userId	Client requesting the current userId to name dictionary from the server.
server	/chatPing userId	Client sending ping to the server.
client	/chatSetAllClients <userId, name pairs>	Server responding to client request with current user dictionary.
client	/chatPong timeOut	Server responding to client ping with the timeout value. Server will expect another call to /chatPing with the clients userId before timeOut seconds has elapsed.

Client Sends A Broadcast Message

Recipient	Command	Description
server	/chatSendMessage userId messageType contents 0	Client sends a message with a single recipientId, the broadcast userId of 0, to the server.
client	/chatEcho userId messageType contents 0	Server sends an echo command back to sending client.
peer	/chatReceive userId messageType contents 0	Server sends the message to all connected peers.

Client Sends A Targeted Message

Recipient	Command	Description
server	/chatSendMessage userId messageType contents <recipientId list>	Client sends a message with one or more nonzero recipientIds to the server.
client	/chatEcho userId messageType contents <recipientId list>	Server sends an echo command back to sending client.
peer	/chatReceive userId messageType contents <recipientId list>	Server sends the message to all peers identified on the list.

Peer Sends A Message To Client

Recipient	Command	Description
server	/chatSendMessage userId messageType contents <recipientId list>	Peer sends a message to server with client's userId in recipientId list.
client	/chatReceive userId messageType contents <recipientId list>	Client receives message from peer via the server.

Client Changes Nickname

Recipient	Command	Description
server	/chatChangeNickName userId newName	Client sends userId and desired new nickname to server.
client	/chatChangeClient /rename userId newName	Server sends user change command to all connected peers including sending client.

Client Times Out

Recipient	Command	Description
client	/clientTimeOut	Server will send one timeout message to client on detection of timeout, and will respond with a clientTimeOut message to all future requests from the client with that userId.
peer	/chatChangeClient userId \timeout	Server will send a client change timeout message to all remaining connected peers.

helpfile source: HelpSource/Reference/SCLOrkChat-OSC-Command-Reference.schelp
link::SCLOrkTools/Reference/SCLOrkChat-OSC-Command-Reference::

SCLOrkChat OSC Command ReferenceExtension

SCLOrkChat OSC Command Reference
Extension