Define and Position Stimuli

Experiments

Testable supports images, text, audio, and video stimuli. This article covers the columns that control what is displayed and where.

Stimulus columns

Use stim, stim2, stim3, … to define stimuli for a trial. When multiple stim columns are filled, by default all stimuli are presented simultaneously on screen.

To present stimuli sequentially (one after another), set each stimulus’s presTime and separate them using timing columns. See Timing Parameters for details on ISI (inter-stimulus interval).

`stimFormat`: what type of content is it?

The stimFormat column tells Testable how to interpret the value of the stim column.

Value	Behaviour
(empty)	Testable auto-detects: image files by extension (.png, .jpg, .gif etc.), audio by extension, video by extension, everything else as text.
`image`	Force display as image
`audio`	Force presentation as audio
`video`	Force presentation as video
`html`	Render the content as raw HTML
`list`	Treat the value as a stimulus list wildcard (see Generating Trials from Stimulus Lists)

`stimSize`: stimulus dimensions

Control the size of your stimulus with the stimSize column. By default, Testable displays stimuli at their original file dimensions.

Width and height (pixels)

stimSize = 300 400

Sets the stimulus to exactly 300 px wide and 400 px tall, regardless of original proportions.

Width only (auto height)

stimSize = 300

Sets the width to 300 px; height scales automatically to maintain the original proportions.

Percentage scaling

stimSize = 150%

Scales both width and height proportionally by the given factor. A 200×400 px image at 150% becomes 300×600 px.

Maximum dimensions

stimSize = max 500 500

Sets an upper bound: stimuli will never exceed these dimensions, but can be smaller depending on their original size. You can also use max 400 to constrain only the width.

`stimPos`: stimulus position

By default, each stimulus is centred on screen. Use stimPos to override this.

Single stimulus positioning:

left, right, top, bottom: predefined positions
x,y number pairs: position in pixels from centre (e.g. -300,0 for 300 px to the left)

Multiple stimuli positioning:

List positions for each stimulus separated by semicolons, matching the order of your stim columns:

stimPos = -300,0; 300,0

This places stim at 300 px left of centre and stim2 at 300 px right.

Random positioning:

stimPos = random

Each stimulus is placed at a randomly selected position.

`stimOptions`: additional display options

stimOptions accepts multiple values separated by semicolons.

Value	Effect
`keep`	Keep a video on screen after it finishes playing (shows last frame)
`noAutoplay`	Require participants to manually start audio/video playback
`muted`	Mute a video stimulus
`controls`	Show browser playback controls for audio/video
`mask`	After presentation, replace the stimulus with a visual mask
`variants: A/B/C`	Randomly select one variant per participant (`/` separates options)

`stimList`: all stimuli in one column

Alternatively to using stim1, stim2, etc., you can specify all stimuli in a single column:

stimList = filename1;filename2;filename3

Separate filenames with semicolons. Do not include file extensions; define those separately in stimFormat.

`audio`: playing audio alongside stimuli

The audio column plays a sound file alongside the visual stimulus in a trial.

audio = mysound.mp3

By default, playback starts immediately after ITI and stops when the trial ends.

Playing audio across multiple trials

Extend playback beyond the current trial using the until: option:

audio = sound1.mp3, until: 20

Stop conditions:

Value	Behaviour
Trial number (e.g. `20`)	Audio stops when that trial is reached
Time elapsed (e.g. `2m30s`)	Audio stops after the specified duration
Trial label (e.g. `partA`)	Audio stops when the trial with that label is reached
`loop`	Audio repeats until the experiment ends or a `stop` command is reached
`end`	Audio plays once for its complete duration, regardless of how many trials it spans

To stop any ongoing audio playback, set audio = stop in any trial.

Customising audio start time

Delay when audio begins playing using the start: option:

audio = sound1.mp3, start: 2000

This delays the audio by 2000 ms after the trial begins (after ITI). You can also write start: delay=3000ms for the same effect.

Combining start and until:

audio = sound1.mp3, until: label1, start: 3000

`mask`: masking stimuli

The mask column replaces a stimulus with a visual mask after its presentation time ends. Useful for backward masking paradigms.

Column: mask
Value: 1 (to enable)

CSS customisation via `stimOptions`

Testable allows you to apply custom CSS styling to stimuli for full control over appearance, rotation, positioning, colour, and more.

How to apply CSS

Use {} brackets inside the stimOptions column with CSS-like syntax. Each property is property: value, separated by ;.

stimOptions = {transform: rotate(45deg)}

Available CSS properties

Property	Example	Effect
Rotate	`{transform: rotate(45deg)}`	Turn by angle
Rotate 3D	`{transform: rotateX(30deg) rotateY(15deg)}`	Tilt along X/Y axes
Scale	`{transform: scale(2)}`	Double the size
Scale axis	`{transform: scaleX(1.5) scaleY(1)}`	Stretch horizontally
Translate	`{transform: translateX(50px) translateY(-20px)}`	Move element
Skew	`{transform: skewX(10deg) skewY(5deg)}`	Distort along axes
Colour	`{transform: rotate(30deg); color: red}`	Combine with colour
Brightness	`{transform: rotate(45deg); filter: brightness(150%)}`	Adjust brightness

Styling multiple stimuli

Separate {} blocks for each stimulus with ;:

stimOptions = {transform: scale(1.5); filter: brightness(50%)};{transform: rotate(30deg); filter: brightness(150%)}

Combining CSS with built-in options

Use , to separate CSS blocks from Testable options like random:

stimOptions = {transform: scale(1.5); filter: brightness(50%)};{transform: rotate(30deg)}, random

Next steps

Define Responses: specify how participants respond
Timing Parameters: control ITI, ISI, presentation time, and response windows
Other Visual Content: fixation cross, trial text, counters, and colours