Get started with WebSocket

Use the WebSocket API to connect a local application to PlayAbility, send controls, read settings, and receive output changes.

ws://127.0.0.1:13123

Your client and PlayAbility must run on the same computer. Keep PlayAbility running while your integration is connected.

Enable the server

Open WebSocket & MCP in PlayAbility’s Inputs/Connections panel and enable Enable WebSocket Server. Enable Require authentication key, then copy the nonempty key into your client’s secret storage.

Connect trusted local applications only. Keep the key out of public code and logs. The Allow WebSocket Inputs toggle is not an access-control boundary, and output state may reach connected clients before authentication. Leave output broadcasting off when you do not need it.

Connect and authenticate

Open a WebSocket connection and wait for the greeting:

{"type":"CONNECT","info":"WebSocket Server Started","authRequired":true}

If authRequired is true, send your key before any other request:

{"type":"AUTH","key":"YOUR_AUTHENTICATION_KEY"}

Wait for:

{"type":"AUTH_OK"}

If authentication is enabled in PlayAbility but authRequired is false, check that the configured key is nonempty. Reconnect and authenticate again after changing the key.

Read the settings

Send a command as a JSON object with a top-level type:

{"type":"GET_SETTINGS"}

The response has type: "SETTINGS_STATE". Its data.settings contains the exposed settings; data.hints explains some of them. See the message reference for all commands and responses.

Responses and output events share the connection. Match messages by type and send requests one at a time. Input events have no execution acknowledgment.

Send controls or receive output

For a control test, enable Allow WebSocket Inputs, Main Output, and the intended output type in PlayAbility. Always pair a press with a release; closing the connection does not release held controls.

• Input events: buttons, axes, keys, and mouse actions.
• Output events: subscribe to changes and read state.
• Runnable examples: JavaScript and Python clients, with a read-only default and an optional button test.
• AsyncAPI specification: downloadable message schemas and examples.

Common problems

Problem	What to check
Connection refused	PlayAbility is running, WebSocket is enabled, and your client uses 127.0.0.1:13123 on the same computer.
AUTH_ERROR or unauthorized error	Use the current key and wait for AUTH_OK before sending requests.
Controls have no effect	Check the event format, Main Output, the output type, and the target device.
No output messages	Enable Allow WebSocket Outputs; automatic messages report changes, so an idle state can remain silent.
A request times out	Check PlayAbility for a pending dialog. Read the current state before retrying an action that may already have completed.

After a disconnect, reconnect, authenticate, and refresh the state you need. Do not automatically replay button presses, imports, or other actions.