
Send to Websocket Action
The Send To Websocket action sends a message from your running study to a program listening on a WebSocket connection, such as a local Python script, a recording device, or an external server. The message can carry the value of a variable, and the action can also send a recorded image, audio, or video file.
Table of Contents
Overview
The Send To Websocket action is listed under the API Actions category in the action selection menu. Together with the Websocket Trigger, it gives a study two-way communication with software running outside Labvanced.
Common Use Cases
The Send To Websocket action is used wherever something that happens in the study should be known outside it.
- Sending event markers to recording systems: at stimulus onset, a response, or a condition change, the study sends a marker to a local script that turns it into a Lab Streaming Layer marker, so it is time-stamped alongside EEG and eye tracking streams. See EEG & Hardware Integrations.
- Passing data to a server: the study sends a participant's response or a computed value to a server that processes it, such as an analysis or machine learning process.
- Sending recorded media: a recorded image, audio, or video file is sent to a program that stores or analyzes it.
How It Works
To access the Send To Websocket action, open the Event System in the Task Editor and select or create an event. In the action area, open the API Actions category and select Send To Websocket.
The action is available once the connection is enabled in the study settings. If Send To Websocket is greyed out in the menu, enable it first:
- Open the
Settingstab. - Open the
Special Featuresdrop-down and find theWebsocket Connectionsection. - Check the option to enable it, then enter the
WebSocket Addressand thePort. The defaults arews://localhostand8081, which connect to a script running on the same computer as the study.
The dialog contains the following:
| Option | Description |
|---|---|
Websocket Address | Shows the address from your study settings. It cannot be edited here. |
Port | Shows the port from your study settings. It cannot be edited here. |
Data Type | Chooses what the action sends. Text / JSON sends a message and an optional variable value. Binary (image/audio/video) sends a recorded file. |
Trigger / message to send | The message label, for example trigger1. This field appears only for Text / JSON. |
Send Variable | The variable whose value is sent. It is optional for Text / JSON and required for Binary (image/audio/video). Selecting it opens the variable picker. |
For Binary (image/audio/video), select a variable that holds a recording, such as the variable of an audio or video recording. If the variable does not hold a recording at that moment, nothing is sent.
What the Receiving Program Gets
The action only has an effect if a program outside Labvanced is listening. That program, usually a short script on the same computer, runs the WebSocket server that the study connects to and reads each message the study sends.
With Text / JSON, each message has two parts:
- A label: the text from
Trigger / message to send, for exampletrigger1. The receiving program uses it to tell message types apart. - Content: the current value of the variable chosen under
Send Variable. If no variable is chosen, the message has a label only.
With Binary (image/audio/video), the action sends the recorded file by itself, without a label.
For the person writing the receiving script, a Text / JSON message is a JSON object with the fields msg for the label and value for the content, and value is null when no variable is chosen. The example scripts in the Labvanced WebSocket API repository on GitHub receive messages from a study and send them on as LSL markers, and are a good starting point. For the connection setup, see the WebSocket API guide.
Workflow Tips
- Start your script before you start the study. The study opens the connection when it starts.
- Test the connection with the study running on the same computer as the script before you collect data. The default
ws://localhostonly reaches programs on that computer. - Send a condition label or trial number in
Send Variablewhen the receiving side needs to know which stimulus a marker belongs to. - Place the action in the event that fires at the moment you want to mark, such as the frame start or a click, so the message is sent at that moment.
Studies & Example Scenarios
Sending a marker to LSL. In the LSL Send Marker library study, an input field supplies the marker value and a button click sends it with this action to a local Python server. The server turns the message into an LSL marker. Use the Inspect option in the library to see the event setup.
Two-way messaging. The Socket Connection Example library study sends a message out of the study with this action and reacts to the replies with the Websocket Trigger.
Further Reading
Websocket Trigger
The paired trigger for reacting to messages that arrive from an external program.
WebSocket API
How to connect a study to a local script or an external server.
Value Select Menu
How to reference values in the dialogs of your actions.
Events Overview
A full introduction to the trigger-and-action logic system in Labvanced.