Importers
PsyCloud importers convert existing experiments into the shared Project Bundle / IR format so they can be inspected, edited, previewed, exported as SDK code, or published after review.
A successful import is not a claim of behavioral equivalence. Always inspect the report, preview the converted study, and verify timing, randomization, scoring, and unsupported plugins before collecting participant data.
Compatibility matrix
| Source | Typical entry point | Studio | CLI | Status |
|---|---|---|---|---|
| jsPsych 6-8 | .html, .js, or project directory | Yes | Yes | Broad coverage; best for standard v7+ plugins. |
| Project Bundle | Bundle directory or .zip with bundle.json | Yes | Yes | Native round trip. |
| PsychoJS | Generated .js file or project archive | Yes, via the import wizard format selector | Yes | Beta; best-effort scheduler/routine extraction. |
| PsychoPy Builder | .psyexp, directory, or .zip containing .psyexp | Not yet | Yes | Best-effort Builder XML import with warnings for unsupported syntax. |
| Custom web experiments | HTML/JS without known framework markers | Not yet | Partial | Usually needs manual porting or jsPsych/PsychoJS structure. |
Studio currently exposes dedicated import cards for jsPsych and Project Bundle. For PsychoJS, open the experiment import wizard and choose PsychoJS from the Format dropdown before uploading.
The CLI auto-detects common inputs:
psycloud import ./experiment.html --dry-run
psycloud import ./experiment.html --out ./imported
psycloud import ./builder-study.psyexp --out ./imported-psychopy
psycloud import ./project.psycloud.zip --out ./roundtripjsPsych adapter coverage
The jsPsych adapter registry covers both v6-style string names and v7+ class names where applicable.
| Family | Supported plugins |
|---|---|
| Keyboard response | html-keyboard-response, image-keyboard-response, audio-keyboard-response, video-keyboard-response |
| Button response | html-button-response, image-button-response, audio-button-response, video-button-response |
| Slider response | html-slider-response, image-slider-response, audio-slider-response, video-slider-response |
| Surveys | survey-text, survey-likert, survey-multi-choice, survey-multi-select, survey-html-form |
| Browser/session utilities | instructions, browser-check, screen-check, fullscreen, preload, call-function |
| Canvas | canvas-keyboard-response, canvas-button-response, canvas-slider-response |
| Categorization | categorize-html, categorize-image, same-different-html, same-different-image |
| Complex paradigms | animation, serial-reaction-time, free-sort, reconstruction |
| Specialized | cloze, external-html, iat-html, iat-image, maxdiff |
Common warning cases include dynamic JavaScript functions, closure variables, canvas drawing that cannot be translated to Draw2D, custom button HTML, media timing differences, and survey layouts that need visual review.
Report semantics
Every serious import workflow should start with the report. The importer report has four status levels and three verification levels.
| Field | Values | Meaning |
|---|---|---|
status | success, partial, compat_only, failed | Whether the source became verified IR, mixed IR/compat, compatibility-only runtime, or could not run. |
verificationLevel | verified, unverified, mixed | Whether the result can be treated as verified PsyCloud IR or still contains unverified segments. |
canRun | true / false | Whether the converted output can be previewed or run at all. |
canPublishVerified | true / false | Whether it is eligible for a verified publish without manual fixes. |
conversionRate | 0 to 1 | Fraction of detected trials converted to PsyCloud IR. |
blockers | Structured blocker list | Custom plugins, call-function, dynamic timelines, parse errors, multi-file issues, or unknown blockers. |
warnings / errors | Message arrays | Review items from extraction, conversion, validation, assets, and framework-specific adapters. |
The CLI writes a project directory plus import artifacts when --out is used:
imported/
project.json
study.json
assets/
import/
report.json
report.md
original/Read import/report.md for human triage, and keep report.json when you want CI or migration
tools to gate on unsupported plugins or canPublishVerified.
Verification workflow
- Run a dry import
Use
psycloud import <source> --dry-runfirst to confirm detection, parseability, plugin coverage, warnings, and blockers without writing a migrated project. - Create an output project
Import with
--out, then inspect the generated project withpsycloud inspectandpsycloud validate. - Preview behavior
Open the converted study in Studio or use workbench previews to compare key screens, trial order, timing, and response collection against the original experiment.
- Fix review items
Replace compat wrappers, unsupported plugins, unverified code steps, or dynamic snippets before treating the result as publishable verified IR.
Known non-goals
- The importer does not guarantee pixel-perfect layout parity.
- Arbitrary JavaScript, custom plugins, and dynamic generated timelines may require manual porting.
- PsychoJS and PsychoPy imports are best-effort and should be treated as migration accelerators, not production-ready conversions.
- Media playback and browser-specific timing should be checked in the same browser class you plan to use for data collection.