stimOptions

Experiments Surveys & forms On form rows only the random flag applies (shuffling the displayed images); playback flags and CSS blocks are experiment-only.

The per-trial stimulus SETTINGS column: shuffle stimulus order with the random keyword (the unconstrained legacy shuffle; constrained ordering lives in the stimOrder column), control audio/video playback (controls, loop, mute, autoplay, keep-on-screen), loop a multi-screen image sequence until a response, and inject per-stimulus inline CSS.

Syntax

Write keywords, separated however you like: random loop muted. The cell is plain text, not JSON, and keywords are recognised anywhere in it. Optionally add one or more CSS blocks {prop: value; prop2: value2}{...} to style individual stimuli.

A random(...) group does not belong here: the constrained ordering specs like random(chunk 2) are the stimOrder column’s grammar, and one left in this cell is a validation error with a pointer there.

Options

Token	Applies to	Effect
random	image trials, word trials, audio/video trials, sort/CFPT-style sortable stims, forms	shuffles the presentation order of the stimuli. For image/word trials the stimuli are shuffled into the display slots, stim-based key scoring follows the content, and click handlers stay attached. For audio/video it shuffles the playback order. For forms it shuffles the images shown
random(...)	—	rejected: constrained ordering specs live in stimOrder
controls	audio/video trials	shows native media controls
loop	audio/video trials	loops the media
loop	image trials	repeats the trial’s screen sequence (presTime/ISI cycle) until a response is registered
muted	audio/video trials	starts the media muted
noAutoplay	audio/video trials	disables autoplay; autoplay is ON by default
keep	audio/video trials	when playback ends the media stays on screen instead of being hidden
{prop: value; ...}{...}	image and word trials	CSS block j applies to stim j+1’s container; removed at trial end
anything else	any	no effect

When random is active, the actual presented order is written to the results column stimOrder_actual as ;-joined ids (image/word: container ids; audio/video: sound3;sound1;...); stimOrder spec trials record their once-per-session resolved order through the same field. Forms save the shuffled image basenames. Otherwise the column records an empty marker.

Defaults & missing values

With the column absent or the cell left empty: no randomization, no CSS. Audio/video plays with autoplay on, controls off, no loop, unmuted, and the element hidden when playback ends.

Works with

• key scoring: with the shuffle and a stim-referencing key, the correct stimulus is tracked through the reorder, so scoring follows the content, not the slot.
• stimPos: positions attach to display slots; randomisation shuffles which stimulus content occupies each slot.
• Multi-screen trials: the shuffle spans all screens, so sequential stimuli reorder across the whole trial; stimScreens grouping is positional, so screen sizes stay fixed while the shuffle changes which stimuli fill them.
• stimOrder: the constrained random(...) ordering specs are that column’s job. The two cannot both randomise one row: a spec next to the bare random keyword here is a validation error either way. Settings (playback flags, CSS blocks) combine freely with a spec on the same row.
• Image loop matters on multi-screen image trials; each loop iteration re-runs the screen sequence until a response arrives.
• CSS reset: injected styles are removed at trial end, so they do not leak into the next trial.

Examples

type	stimFormat	stim1	stim2	stim3	key	stimOptions
test	.jpg	catA	catB	catC	stim2	random

The three images are displayed in shuffled slots; the response is scored correct when the participant picks catB wherever it landed, and the shuffled order is saved in stimOrder_actual.

type	stimFormat	stim1	stimOptions
learn	.mp4	intro_video	controls muted keep

Video shows native controls, starts muted, autoplays (no noAutoplay), and stays visible after it finishes.

type	stimFormat	stim1	stim2	stimOptions
test	word	LEFT	RIGHT	{color: red; border: 2px solid black}{color: blue}

First word rendered red with a black border, second blue; styles are removed when the trial ends.

Tips & gotchas

• Keywords match as substrings and are case-sensitive: random anywhere in the cell (including inside a CSS value like background: url(random.png)) triggers randomization, and loop matches inside longer words; Random or LOOP do NOT match. Column names are case-insensitive, cell values are not.
• Not JSON: JSON-style values like {"loop": true} are not read as options; the braces are treated as a (bogus) CSS block, and the substring loop inside it would still enable looping.
• CSS blocks are positional: to style only stim2, provide an empty first block: {}{color: red}. There is no way to target the target or mask.
• Use hyphenated CSS property names: camelCase names would apply but not reliably reset at trial end.
• keep only affects the hide-on-ended behavior; with multiple media stimuli, keep keeps the LAST played medium visible.
• The shuffle reshuffles every display: a repeated trial gets a fresh order each time it shows. For an order that is drawn once and repeated within a session, use a stimOrder spec.

Common combinations

stimOptions appears in these worked recipes:

• Click the target: Present several images as clickable response options and score the clicked target correctly even when display positions are shuffled.
• Side-by-side comparison: Show two images left and right of centre and let the participant click their choice, scored correctly whichever side the target lands on.