README
¶
goxpyriment
-
Goxpyriment is a software framework for programming behavioral and cognitive experiments using the Go programming language. It was designed to address some limitations of existing Python-based experiment tools, particularly the runtime environment complexity that frequently complicates deployment across laboratories. Because Go is a compiled language that can natively embed assets (e.g., graphics, audio files, and stimulus lists), Goxpyriment compiles entire experiments into single, self-contained executable binaries with zero runtime dependencies. This drastically simplifies distribution to collaborators and testing computers. The library includes an array of visual stimuli (text, shapes, images, Gabor patches, motion clouds, ...) and audio capabilities (WAV playback and tone generation). A lot of effort was devoted to ensure timing reliability. For instance, input events are timestamped by the operating system at hardware-interrupt time, so reaction times are computed by subtracting two OS-level timestamps rather than relying on continuous polling. The framework also supports sending and receiving TTL signals to synchronize with various external equipment. Go's garbage collector can be disabled, greatly reducing the probability of unpredictable pauses that could corrupt stimulus timing. Finally, a set of over forty psychology experiments implemented in Goxpyriment are provided that promote not only learning by humans but also improve the ability of modern AI-assisted coding tools to help program experiments. The framework is released under the GNU General Public License v3.
Remark: If you are looking for a simple experiment generator - with fixed stimulus presentation schedule, check out Gostim2 which does not require any coding.
Documentation
The top navigation bar provides access to various documentation guides.
Start here — install and build your first experiment
- Install Go and build the bundled examples. [PDF]
- Creating Your Own Experiment — a step-by-step beginner guide from an empty folder to a shareable executable.
- Getting Started — worked tutorials: trials, data logging, RSVP streams, reaction times. [PDF]
User Manual — core concepts explained in depth: rendering model, timing, input, data, streams, audio, and experimental design. [PDF]
API Reference — complete function and type reference, organized by package. [PDF]
Misc — focused how-to guides: migrating from PsychoPy / Expyriment / Psychtoolbox, checking your computer's timing, video playback, packaging & sharing binaries, Linux tuning, and more, all found under the Misc tab in the navigation bar at the top of the page.
In addition, if you clone goxpyriment, you can run pkgsite from the root folder to view the source code documentation.
Gallery of ready-to-run experiments
Browse the gallery of over fifty example experiments and demos (pre-built binaries (ready-to-run apps) are available for Windows, macOS, and Linux).
Support
- Google group — Forum
- Report bugs at https://github.com/chrplr/goxpyriment/issues
Background
The framework is described in a short paper: Goxpyriment: A Go Framework for Behavioral and Cognitive Experiments.
Goxpyriment is written in Go and relies on the SDL3 library through the go-sdl3 bindings.
The original inspiration was expyriment.org, a lightweight Python library for cognitive and neuroscientific experiments (Krause & Lindemann, 2014. Behavior Research Methods, 46(2), 416–428. https://doi.org/10.3758/s13428-013-0390-6).
License & citation
GNU GPL v3 — see LICENSE.
Please cite as:
Christophe Pallier (2026) chrplr/goxpyriment. Zenodo. https://doi.org/10.5281/zenodo.19200598
Christophe Pallier, 2026.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apparatus provides the low-level input/output subsystems for goxpyriment:
|
Package apparatus provides the low-level input/output subsystems for goxpyriment: |
|
Package clock provides timing helpers: Wait, GetTime, and a Clock for measuring durations and sleeping until a target offset.
|
Package clock provides timing helpers: Wait, GetTime, and a Clock for measuring durations and sleeping until a target offset. |
|
cmd
|
|
|
gen-gallery
command
gen-gallery regenerates the example tables in docs/GalleryOfExamples.md from per-example meta.yaml files.
|
gen-gallery regenerates the example tables in docs/GalleryOfExamples.md from per-example meta.yaml files. |
|
gen-readme
command
gen-readme regenerates README.md (repo root) from docs/index.md.
|
gen-readme regenerates README.md (repo root) from docs/index.md. |
|
gen-wasm-exports
command
Command gen-wasm-exports generates the exhaustive list of C symbols that must be passed to Emscripten's -sEXPORTED_FUNCTIONS when linking SDL3.js/.wasm for a goxpyriment WebAssembly (GOOS=js) build.
|
Command gen-wasm-exports generates the exhaustive list of C symbols that must be passed to Emscripten's -sEXPORTED_FUNCTIONS when linking SDL3.js/.wasm for a goxpyriment WebAssembly (GOOS=js) build. |
|
get-display-info
command
get-display-info queries every connected display via SDL3 and prints its properties: name, bounds, current mode, desktop mode, content scale, orientation, and the full list of available fullscreen resolutions.
|
get-display-info queries every connected display via SDL3 and prints its properties: name, bounds, current mode, desktop mode, content scale, orientation, and the full list of available fullscreen resolutions. |
|
gv-convert
command
Command gv-convert converts a video file into the .gv format that goxpyriment's stimuli.GvVideo and media.Movie play.
|
Command gv-convert converts a video file into the .gv format that goxpyriment's stimuli.GvVideo and media.Movie play. |
|
gv-getinfo
command
Command gv-getinfo prints the header and index-table summary of a .gv video file: frame count, frame size, frame rate, pixel format, and how well the frames compressed.
|
Command gv-getinfo prints the header and index-table summary of a .gv video file: frame count, frame size, frame rate, pixel format, and how well the frames compressed. |
|
Package control manages the overall state and initialization of an experiment.
|
Package control manages the overall state and initialization of an experiment. |
|
Package design provides experiment structure types (trials, blocks, factors) and randomization helpers for building experiment designs.
|
Package design provides experiment structure types (trials, blocks, factors) and randomization helpers for building experiment designs. |
|
Package geometry provides point/distance and coordinate conversion helpers (Euclidean distance, Cartesian–polar conversion, degree–radian).
|
Package geometry provides point/distance and coordinate conversion helpers (Euclidean distance, Cartesian–polar conversion, degree–radian). |
|
Package media provides multi-movie playback with shared master-clock synchronisation, look-ahead frame conditions, and post-vsync display events suitable for wiring to hardware triggers.
|
Package media provides multi-movie playback with shared master-clock synchronisation, look-ahead frame conditions, and post-vsync display events suitable for wiring to hardware triggers. |
|
present
Package present provides PresentTimer backends that report hardware-verified vsync timestamps for an apparatus.Screen.
|
Package present provides PresentTimer backends that report hardware-verified vsync timestamps for an apparatus.Screen. |
|
Package staircase implements adaptive psychophysical threshold estimation.
|
Package staircase implements adaptive psychophysical threshold estimation. |
|
Package sysinfo collects and formats hardware and software information about the running system (machine type, OS, CPU, memory, GPU, audio).
|
Package sysinfo collects and formats hardware and software information about the running system (machine type, OS, CPU, memory, GPU, audio). |
|
Package triggers provides hardware trigger interfaces for synchronising stimuli with external recording equipment (EEG/MEG amplifiers, oscilloscopes, photodiodes), and for reading TTL-level response signals.
|
Package triggers provides hardware trigger interfaces for synchronising stimuli with external recording equipment (EEG/MEG amplifiers, oscilloscopes, photodiodes), and for reading TTL-level response signals. |
|
Package units provides unit conversions for vision-science experiments.
|
Package units provides unit conversions for vision-science experiments. |