Close

Palette:signalingServer

Summary

The signalingServer COMP is a component that can be used to run a signaling server within TouchDesigner.

A signaling server is used as an intermediary between clients to route arbitrary messages between a client A and a client B, where A and B don't know how to reach each other and should "signal" themselves.

More details about the Signaling API are available in this page at the Signaling API section. The current communication protocol is WebSocket.

It is often used as part of WebRTC sessions.

PythonIcon.pngPalette:signalingServer Ext


Signaling API

The Signaling API is describing the message types being exchanged between a signaling server and its clients or between client and client when they are routing message through the signaling server.

If a 3rd party application wishes to connect with TouchDesigner's own signaling server, the messages being exchanged should comply with the Signaling API described in the following section.

Note that some components can be developed to subscribe to signaling messages through the signalingClient COMP Subscribe() method.

i.e. The WebRTC COMP is subscribing to messages being exchanged through the signaling server and clients, and complying with the Signaling API.

JSON Schema

Available in version 1.0.0 and above. All signaling messages implemented in the current Signaling API have a matching JSON Schema file.

Making use of those schemas, a user can validate its signaling messages before sending them to the server.

On the signalingServer COMP and the signalingClient COMP, find the JSON Schema related parameters. You can validate messages being sent from / to each signaling components. While you would likely not use schema validation in a production environment, they are useful during development.

When signaling messages are failing to be parsed by the target of the message, you will get detailed information if for some reason your message is not complying with our API. It is particularly useful if you write a signalingClient from scratch in another environment than TouchDesigner and wish to connect with the signalingServer we provide.

We provide a default endpoint where the signalingServer and signalingClient COMPs can fetch the schemas. If you do not have an internet connection or if the endpoint is unavailable for some reason, you can find the latest schema versions at the top of this page or in this GitHub repository. While we try to keep the following section describing signaling messages up to date, the one source of truth will always be in this GitHub repository.

The repository also includes Signaling messages schemas for signalingTypes specific to the WebRTC COMP.

Note: When using remote schemas, we attempt to cache the schemas (and some related objects necessary to validation) progressively as new signaling message types are being sent / received. This cache can be emptied when pulsing the "Clear schema cache" parameter of the component. The same caching occurs on the Palette:signalingClient COMP as well. With that in mind, note that the first few messages being exchanged could trigger frame drops.

When using local schema files, the cache is being built when the folder to the schema files is being set or changing using the "Local Schema Folder" parameter. You can clear the cache as well and it will be rebuilt on the next signaling messages exchange.


Signaling messages, base structure.

All signaling messages have the mandatory properties:

  • metadata - The mandatory metadata dictionary describing the API version and its origin
  • signalingType - The type of signaling message that is being sent or received (ClientEnter, ClientEntered, ClientExit, Clients)
  • content - The content of the message being carried over the signaling API

Additionally, the following properties can be present for some specific message types:

  • sender - The sender address in the format IP:port as perceived by the signaling server
  • target - The target address in the format IP:port as set by the sender

Metadata

The metadata dictionary is made of the following mandatory properties:

  • apiVersion - The version number of the Signaling API being implemented
  • compVersion - The version number of the component, or the external application version number, from which the message originated
  • compOrigin - The path of the component within the TouchDesigner project, or the URI of an external application, from which the message originated
  • projectName - The name of the TouchDesigner project, or external application, from which the message originated


signalingType - ClientEnter

A signaling message sent from the signaling server to clients in the signaling session to make them aware that a client entered the signaling session.

The signaling message type property should be set to ClientEnter, and a Client dictionary should be set in the client property of the content dictionary.

"content": {
   "client": {
      "id":"The unique identifier of the client generated by the signaling server when entering the signaling session",
      "address":"The address of the client as perceived by the signaling server in the IP:port format",
      "properties":"An arbitrary dictionary that can be used to carry custom properties across the signaling protocol. A 'domain' property should be available in the object."
   }
}


signalingType - ClientEntered

A signaling message sent from the signaling server to a client to acknowledge that the client entered the signaling session and was registered by the signaling server.

The signaling message type property should be set to ClientEntered, and a Client dictionary should be set in the self property of the content dictionary.

"content": {
   "self": {
      "id":"The unique identifier of the client generated by the signaling server when entering the signaling session",
      "address":"The address of the client as perceived by the signaling server in the IP:port format",
      "properties": "An arbitrary dictionary that can be used to carry custom properties across the signaling protocol. A 'domain' property should be available in the object."
   }
}


signalingType - ClientExit

A signaling message sent from the signaling server to clients in the signaling session to make them aware that a client left the signaling session

The signaling message type property should be set to ClientExit, and a Client ID should be set in the id property of the content dictionary.

"content": {
      "client": {
         "id":"The unique identifier of the client generated by the signaling server when entering the signaling session",
         "address":"The address of the client as perceived by the signaling server in the IP:port format",
         "properties": "An arbitrary dictionary that can be used to carry custom properties across the signaling protocol. A 'domain' property should be available in the object."
   }
}


signalingType - Clients

A signaling message sent from the signaling server to a client to make it aware of other signaling clients within the signaling session

The signaling message type property should be set to Clients, and a list of clients should be set in the clients property of the content dictionary.

"content": {
   "clients": [{
   "id":"The unique identifier of the client generated by the signaling server when entering the signaling session",
   "address":"The address of the client as perceived by the signaling server in the IP:port format",
   "properties":"An arbitrary dictionary that can be used to carry custom properties across the signaling protocol. A 'domain' property should be available in the object."
   }]
}


Parameters - Signaling Server Page

Active Active - Start or stop the signaling server.

Restart Restart - Restart the signaling server and reset all states.

Port Port - Port on which the signaling clients can connect to the signaling server and on which the signaling server can receive messages.

Secure (TLS) Secure - When enabled, this will force clients to connect to the signaling server using TLS and exchange messages securely.

Private Key File Path Privatekey - The required private key when the signaling server should be secure.

Certificate File Path Certificate - The required certificate when the signaling server should be secure.

Certificate Password Password - The required certificate password when the signaling server should be secure.

Pass Through Passthrough - When enabled, if messages sent to the server do not have the property target, the messages are broadcasted to all clients in the signaling session and on the same domain.

Use JSON Schema In Usejsonschemain - Validate incoming Signaling API messages against JSON Schema.

Use JSON Schema Out Usejsonschemaout - Validate outgoing Signaling API messages against JSON Schema.

Use local RefResolver Uselocalrefresolver - Use JSON Schema files installed locally rather than validating from remote sources. Schema files available at https://github.com/TouchDesigner/SignalingAPI

Local Schema Folder Localschemafolder - A folder where the JSON Schema files for the Signaling API are available locally.

Clear schema cache Clearschemacache - Signaling API schema files are loaded once. Clearing the cache force them to reload on the next call that requires JSON Schema.

Signaling API Version Signalingapiversion - The Signaling API version. When a signaling client is being used, the API version of both the server and client should match.

Signaling API Schema Endpoint Signalingapischemaendpoint - The endpoint being used to fetch the JSON Schema files.


Parameters - Logger Page

Enable Log Enablelogging - Enable advanced log features. Useful to debug and track the signaling server activity.

Log to File Logtofile - When enabled, log messages will be written to a time rotated log file.

Log Folder Logfolder - Path to the folder in which the log files should be written.

File Rotation Filerotation - Number of backup files to be kept when rotating log.

Log to Textport Logtotextport - When enabled, log messages will be displayed in the textport.

Log to Status Bar Logtostatusbar - When enabled, log messages will be displayed in the status bar.

Log Level Loglevel - - Filter level of log messages. The selected level is included as well as all levels above. I.e. if Warning is selected, Warning and Error messages will be included while Info messages will be excluded.

  • INFO INFO -
  • DEBUG DEBUG -
  • WARNING WARNING -
  • ERROR ERROR -
  • CRITICAL CRITICAL -


Parameters - About Page

Help Help - Open COMP Help page in external browser.

Version Version - The COMP version number.

TouchDesigner Build: