GitLab

OpenLP provides a simple WebSocket server to provide up to date information about the state of the program. Once connected to the server, OpenLP will provide updates whenever the state of the program changes.

The default port for the WebSocket server is 4317. This is not the same as the HTTP API and web remote.

Note

The OpenLP server is only available on your local network. OpenLP does not perform any sort of port forwarding and the server is not capable of handling large loads. It is not recommended to expose the OpenLP server to the internet unless you know what you are doing.

Program State

The state of OpenLP is sent in a JSON format. The response will contain JSON data types including { } JSON object, St JSON string, TF JSON boolean and Nm JSON number as described below:

{} - Root of the response
└── {} results: - Containing object for state.
    ├── Nm counter: - Number incremented if the live display has changed.
    ├── Nm service: - Number incremented if the service is modified.
    ├── Nm slide: - Number incremented if the service is modified.
    ├── St item: - The service unique identifier for the current service item.
    ├── TF twelve: - Is using twelve hour time.
    ├── TF blank: - Is display blank.
    ├── TF theme: - Is display showing the theme.
    ├── TF display: - Is display showing the desktop.
    ├── Nm version: - Version number (not sure what for, hard coded as 3 atm).
    ├── TF isSecure: - Is authentication enabled for login required HTTP API endpoints.
    └── St chordNotation: - Notation used for chords, can be `english`, `german` or `neo-latin`.

Examples

Javascript

This script connects to the WebSockets server and prints to the console every time the state changes:

const host = window.location.hostname;
const websocket_port = 4317;

ws = new WebSocket(`ws://${host}:${websocket_port}`);
ws.onmessage = (event) => {
    const reader = new FileReader();
    reader.onload = () => {
        const state = JSON.parse(reader.result.toString()).results;

        // Do stuff here
        console.log(state);

    };
    reader.readAsText(event.data);
};

If you are not running this on a OpenLP stage view, you might want to change window.location.hostname to the IP of the computer running OpenLP.