The first caution to be aware of here is that PsychoJS was only written in 2016. It hasn’t been widely battle-tested and almost certainly has some rough edges. Use it carefully and check your study does what you expect.
For an in-depth examination of the pros and cons of running studies online (including a consideration of timing issues), see The timing mega-study (Bridges et al., 2020).
The PsychoJS library looks much like its PsychoPy (Python) equivalent; it has classes like Window and ImageStim and these have the same attributes. So, from that aspect, things are relatively similar and if you already know your way around a PsychoPy script then reading PsychoJS code should be fairly intuitive.
There are a few key differences that you need to understand moving from Python code to the equivalent PsychoJS script.
Resources for your study (images, conditions files etc.) must be in the resources folder next to the html file that PsychoPy® outputs. In most cases PsychoPy® can find these and include them automatically but if your study uses code components then the resource files needed will need to be specified.
Most of the issues below affect your study if you have additional code components inserted into the study and do not affect pure Builder-based designs.
In general timing of web-based experiments will be poorer than locally-run studies. That said, we think PsychoJS will have timing about as good as it can be! What are the specific considerations?
Variable internet connection: Surprisingly no, this isn’t one to worry about! PsychoJS will make sure that the script and all the recourses for your study (image files etc) are downloaded to the computer beforehand. On a slow internet connection it may take longer for your study to start but the performance won’t be limited by that while it runs. Happy days!
Visual stimuli: PsychoJS is using WebGL (high performance web rendering using advanced graphics card features) and we have confirmed that PsychoJS is able to run with frame-precise timing. That means, if you ask for a stimulus to last for, say, 6 frames then you will get exactly 100 ms of stimulus presentation.
Response timing: Again this won’t be affected by your internet connection (because the keypresses are being time-stamped locally, at your computer, not by the web server). The major problem, as with any software, is that keyboards have long and variable latencies (10-30 ms typically). On a local lab-based setup you can get around this by using custom hardware (a button box) but this obviously isn’t possible when your user is anywhere in the world!
As a result, PsychoJS needed something to control the running order of the different parts of the script (e.g. the trials need to occur one after the other, waiting for the previous one to finish). To do this PsychoJS adds the concept of the Scheduler. For instance, you could think of the Flow in PsychoPy as being a Schedule with various items being added to it. Some of those items, such as trial loops also schedule further events (the individual trials to be run) and these can even be nested: the Flow could schedule some blocks, which could schedule a trials loop, which would schedule each individual trial.
If you export a script from one of your Builder experiments you can examine this to see how it works.
Some people will be delighted to see that in PsychoJS scripts output by Builder there are functions specifying what should happen at different parts of the experiment (a function to begin the Routine, a function for each frame of the Routine etc.). The essence of the PsychoJS script is that you have any number of these functions and then add them to your scheduler to control the flow of the experiment.
We’d recommend running on an updated browser but pretty much any modern browser (released since roughly 2011) should be able to run these studies. It needs to support HTML5/canvas and ideally it would support WebGL (if not Canvas then will used but that is less efficient).
Specifically, these support Canvas (minimum requirement):
Firefox 10+ (released 2012)
Chrome 11+ (2011)
Safari 2.0+ (2005)
Opera 12+ (2011)
Internet Explorer 9+ (released in 2011) but we really recommend you avoid it!
Browsers supporting WebGL (hardware-accelerated graphics in the browser):
Firefox 15+ (2012)
Chrome 11+ (2011)
Safari 5.1+ (2011/12?)
IE 11+ (2013)