The ProPresenter TCP/IP API is an alternative way to access ProPresenter’s HTTP-based API. It allows a remote system with no HTTP capability to to access a broad subset of ProPresenter’s API via a simple TCP/IP network socket. This is more of an advanced communication protocol that may not be used by everyone, but it is available, should someone need it!

TCP/IP connections are just viewed as streams of text. Each request and response is a serialized JSON object that fits on a single line terminated by a carriage-return/line-feed (CRLF) pair (\n).

Requests

Each request consists of a JSON object with the following basic structure, and the below text is a sample request to add a message to a stage screen as a Stage Message.

{
"url": "v1/stage/message",
"method": "PUT",
"body": "This is the stage message",
"chunked": false
}

The various request members supported are:

• url - This member is mandatory, and contains the relative URL of the endpoint that is being requested, as per the HTTP API documentation.
• method - This member is optional. It defaults to GET if body is not specified and POST if body is specified. The value of this member should match what is required in the API documentation for the specified endpoint.
• body - This member is optional, and contains any post data that should be sent to the endpoint, as per the API documentation. This member is a full JSON object (see the examples below), not a string containing serialized JSON. Note that this member is mandatory if the specific API endpoint requires post data to be sent. Refer to the HTTP API documentation for details.
• chunked - This member is optional and causes the endpoint to send streaming updates to the socket. Each update generates a single one-line response.

Any other members that are present are ignored.

Responses

A response can be in one of two formats.

{
"url": "v1/stage/message",
"data": "This is the stage message"
}

Or

{
"url": "v1/this_url_does_not_exist",
"error": "404 Not Found"
}

The response has only three possible members:

• url - This member will always be present and contains the same URL as the request. Note that if the request is malformed and the URL cannot be read, this member may be an empty string.
• data - This member will only be present if the request was successful and contains data. As per the body member of the request, this is not a string containing serialized JSON, it is a full JSON object.
• error - This member will only be present if the request failed. It is a string and contains the same HTTP error data as would be returned via the HTTP API.

Examples

Retrieve the stage message

Request: {"url":"v1/stage/message"}

Response: {"url":"v1/stage/message","data":"This is the stage message"}

Set the stage message

Request: {"url":"v1/stage/message","method":"PUT","body":"This is the new stage message"}

Response: None

Get the system time (streaming)

Request: {"url":"v1/timer/system_time","chunked":true}

Response:

{"data":1721367787,"url":"v1/timer/system_time"}
{"data":1721367788,"url":"v1/timer/system_time"}
{"data":1721367789,"url":"v1/timer/system_time"}
{"data":1721367790,"url":"v1/timer/system_time"}