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 Apache License 2.0.
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.
Everything in one file: goxpyriment-docs.pdf — every page below as a single searchable PDF, one chapter each, with a full table of contents and bookmarks. Use it when you want to search the whole documentation at once rather than a page at a time. The individual PDFs linked beside each guide are the same content, split.
Start here — install and build your first experiment
- Read Install 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, giving your experiment real-time priority on Linux, 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
Apache License 2.0 — see LICENSE and NOTICE.
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-book
command
gen-book concatenates the documentation in docs/ into one Markdown file that pandoc can turn into a single PDF, each page becoming a chapter.
|
gen-book concatenates the documentation in docs/ into one Markdown file that pandoc can turn into a single PDF, each page becoming a chapter. |
|
gen-download-index
command
gen-download-index generates the download page published alongside the per-app zips in the Cloudflare R2 bucket served at downloads.pallier.org.
|
gen-download-index generates the download page published alongside the per-app zips in the Cloudflare R2 bucket served at downloads.pallier.org. |
|
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. |
|
gen-wasm-launcher
command
gen-wasm-launcher writes the HTML page that runs one experiment in a browser, for publication under downloads.pallier.org/builds/{sha}/wasm/{app}/.
|
gen-wasm-launcher writes the HTML page that runs one experiment in a browser, for publication under downloads.pallier.org/builds/{sha}/wasm/{app}/. |
|
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. |
|
timing-drift
command
Command timing-drift joins an external instrument's event log to goxpyriment's own run CSV and reports whether the framework's idea of when a frame appeared walks away from the actual photons.
|
Command timing-drift joins an external instrument's event log to goxpyriment's own run CSV and reports whether the framework's idea of when a frame appeared walks away from the actual photons. |
|
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 eyetracker provides a vendor-neutral interface to gaze trackers, and a socket client for hardware whose only API is a C SDK.
|
Package eyetracker provides a vendor-neutral interface to gaze trackers, and a socket client for hardware whose only API is a C SDK. |
|
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 adapts the vblank clock to MovieManager's presentation model.
|
Package present adapts the vblank clock to MovieManager's presentation model. |
|
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. |
|
Package vblank reports the OS-measured time of a display's vertical blank.
|
Package vblank reports the OS-measured time of a display's vertical blank. |