audio

Experiments

audio plays an auxiliary/background audio file over a visual trial (images or words), independent of the stimN stimuli. It supports start-delay and stop conditions so a track can span multiple trials, loop, or be cut at a given trial.

Syntax

Put the audio filename, including its extension, in the cell of the trial where it should play, e.g. ambience.mp3. The full grammar:

filename.mp3
filename.mp3, until: END_CONDITION
filename.mp3, start: DELAY
filename.mp3, start: DELAY, until: END_CONDITION
stop

Options follow the filename, separated by commas, in either order; spaces inside a condition are ignored. The filename must always include its extension (stimFormat is not applied to this column), and the file is loaded from the project’s stimuli. Leave the cell empty for no audio.

Options

Value / condition	Behavior
empty cell	No audio
filename.mp3	Plays during this trial; stops when the trial ends
stop	Stops any currently playing background audio at this trial
until: Nt (e.g. 5t)	Loops; stops after N trials have ended
until: XmYs or Ys (e.g. 1m30s, 45s)	Loops; stops after that much time
until: N (digits)	Loops; stops when spreadsheet row N (counted including the header row) starts
until: loop	Loops indefinitely across trials; only a later stop, an until row hit, or the end of the experiment stops it
until: end	Plays once, NOT stopped at trial end; runs until the file finishes or the experiment ends
until: <label> (word characters)	Loops; stops when the trial whose label column matches starts
start: delay=Xms / start: X / start: Xms	Delays playback X ms after the inter-trial interval ends

Defaults & missing values

When the column is absent or the cell is left empty, no background audio plays on that trial. Without an until: condition a track does not loop and stops when its trial ends, so the default lifetime is exactly one trial. All background audio stops at the end of the experiment.

Works with

• Trial types: background audio only plays on image and word trials. On instructions, audio, video, survey, or form trials the cell is accepted but nothing plays, and stop on such trials does nothing either. The row-based stops (until: N or a label) DO fire on any trial type, including form trials.
• ITI: with an ITI greater than 0, the visual stimuli wait until the audio is ready to play before showing, so audio start lines up with stimulus onset; with no ITI the stimuli show immediately.
• Media preloading (project setup option): the file named in audio is preloaded only if the value contains .mp3. Officially only .mp3 is supported; other formats break when preloading is on, and without preloading they may or may not play depending on the browser.
• Shared player: background audio uses the same player as audio-stimulus trials, so a trial with an .mp3 stimFormat takes the player over.
• Autoplay gate: any filled audio cell counts as media in the project, which inserts the “enable media autoplay” screen at the start of the experiment.
• until: Nt counting: the countdown decrements once per trial end, including the trial that started the audio.

Examples

type	stimFormat	stim1	audio	presTime
test	.jpg	scene1	ambience.mp3	5000

ambience.mp3 plays during this image trial only.

type	stimFormat	stim1	audio
test	.png	item1	music.mp3, start: 500ms, until: 10t

Music starts 500 ms after the ITI, loops, and stops after 10 trials end.

type	stimFormat	stim1	audio
test	word	ready	drone.mp3, until: loop
...
test	word	done	stop

Drone loops across trials until the later trial whose audio cell is stop.

Tips & gotchas

Caution

The editor preview only plays the file; until: and start: options are ignored there. Test them in a real run of the experiment.

• until: N counts spreadsheet rows including the header row, while until: <label> targets the labeled trial directly; the two addressing schemes differ.
• A minutes-only time like until: 2m is NOT read as 2 minutes: because a time needs a seconds part, it is treated as spreadsheet row 2 instead. Write 2m0s for a 2-minute duration.
• stop cannot stop a track started with until: end. Such a track ends only when the file finishes, the experiment ends, a later trial’s audio cell loads a different file, or an audio/video stimulus trial takes over the player.
• If an audio file fails to load, participants see an alert and the load is retried every 10 seconds (outside preview).

Common combinations

audio appears in these worked recipes:

• Ambient audio across trials: Start a looping background track on one trial and cut it at a later trial, leaving the rest of the block silent.