CSV manifests
CSV manifests let you describe self-hosted stimuli explicitly. Upload a .csv file with one row per stimulus.
group,condition,url,file_ext
source_1,model_a,https://cdn.example.com/datasets/source_1/model_a.wav,
source_1,model_b,https://cdn.example.com/datasets/source_1/model_b.wav,
source_2,model_a,https://cdn.example.com/datasets/source_2/model_a.wav,
source_2,model_b,https://cdn.example.com/datasets/source_2/model_b.wav,wav
Columns
| Column | Required | Description |
|---|---|---|
group | Yes | The stimulus group name. Leave empty to use root. |
condition | Yes | The condition or stimulus name inside the group. |
url | Yes | The URL of the remote stimulus. |
file_ext | No | File extension appended to the stimulus name. See the notes on json and req.json below. |
The file_ext value sets the extension of the stimulus name: the condition model_a with file_ext wav becomes the stimulus model_a.wav. It should not include a leading dot. For example, use wav, not .wav. It must be one of the supported extensions — wav, mp3, ogg, png, jpg, jpeg, gif, jp2, jxl, mp4, json, req.json, txt, js, html, htm — otherwise processing the dataset fails with Unsupported file extension.
Setting file_ext to json appends .json to the stimulus name. A name ending in .json, except .req.json, makes it a configuration stimulus without overriding the media type inferred from the URL.
req.json is the one file_ext value that changes the stimulus's media type: a stimulus name ending in .req.json becomes an API request stimulus, whatever the URL looks like. Set file_ext to req.json, or include .req.json in the condition name and leave file_ext empty. A hosted .req.json URL alone would otherwise be classified as a config file.
Mabyduck infers the media type of a self-hosted stimulus from the extension in the url itself, not from file_ext. A URL whose path has no extension is treated as an embedded web page, whatever file_ext says, unless it is req.json: the dataset will not be offered when creating an audio, image, or video experiment, and no audio or video metadata is extracted for it. Make sure audio, image, and video URLs end in a real file extension.
How groups and stimuli are created
Each row creates one stimulus in the specified group.
group,condition,url,file_ext
prompt_001,elevenlabs,https://cdn.example.com/audio/001/elevenlabs.wav,wav
prompt_001,cartesia,https://cdn.example.com/audio/001/cartesia.wav,wav
Creates:
- Group:
prompt_001 - Stimuli:
elevenlabs.wavandcartesia.wav
The same group and condition pair can only appear once in a CSV manifest.
Embedded frontends
CSV manifests are useful when the stimulus URL points to a hosted frontend rather than a media file. For embedded experiments, the url can point to the remote page that should be loaded in the experiment iframe, while group and condition control how that stimulus is named in Mabyduck.
group,condition,url,file_ext
task_1,variant_a,https://frontend.example.com/task-1?variant=a,html
task_1,variant_b,https://frontend.example.com/task-1?variant=b,html
Requirements
The CSV file must include a header row with group, condition, and url. The optional file_ext header is only needed when you want to provide file extensions explicitly.
The condition and url fields cannot be empty. In normal use, URLs should start with https://.
Localhost and private network URLs are blocked outside development environments.