Prolific Smart Glasses POV Video Collection

Recruit real smart-glasses owners and collect first-person (POV) video from them — end to end, from one config file. Built on Prolific's AI Task Builder Collections API.

Submissions stream in live — each with the participant's video, glasses, and demographics.

Want real first-person video — a walk, a view, a hands-free task — shot on glasses like Ray-Ban Meta or Viture? This toolkit takes you from "empty config" to "paid participants" in four steps.

Collect → Watch → Review → Reward

Four scripts, all driven by config.yaml + a Prolific token in .env.

	Tool	What it does
①	prolific_video_collection.py	Create + launch the study, check status, download videos.
②	dashboard.py	Live dashboard — watch submissions arrive in real time.
③	review-app/	Curate the clips, pick who to follow up with.
④	send_bonus_message.py	Pay bonuses and/or message your picks.

Quickstart

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # then add your Prolific token + workspace/project ids

PROLIFIC_API_TOKEN=your_token_here       # app.prolific.com → Settings → API tokens
PROLIFIC_WORKSPACE_ID=your_workspace_id  # or: python prolific_video_collection.py discover
PROLIFIC_PROJECT_ID=your_project_id      # or: python prolific_video_collection.py discover

.env is git-ignored — credentials never touch config.yaml or the code.

Note: AI Task Builder Collections must be enabled on your account. Launch and manage these studies via this script or the CLI — the researcher web UI isn't fully wired up for them yet.

① Collect

python prolific_video_collection.py check     # token works?
python prolific_video_collection.py create    # build collection + draft study
python prolific_video_collection.py launch    # publish — recruits real people, costs money!
python prolific_video_collection.py status    # check progress anytime
python prolific_video_collection.py results   # download videos → ./results/

launch spends real money, so it asks first (--yes to skip). Videos default to MANUALLY_REVIEW so you approve each one. create saves the new collection/study IDs to prolific_state.json so every later step knows what to act on.

Command	API call
create	POST /data-collection/collections, POST /studies/
launch	POST /studies/{id}/transition/
status	GET /studies/{id}/, GET /studies/{id}/submissions/counts/
results	POST /data-collection/collections/{id}/export

Target smart-glasses owners. The study ships with a filter so only AR / smart-glasses owners are recruited (config.yaml → study.filters):

filters:
  - filter_id: "head-mounted-devices"
    selected_values: ["3", "4", "5", "6"]   # Meta Aria, Ray-Ban Meta, HoloLens, Generic AR

Values: 0 Quest 2 · 1 Quest 3 · 2 Vision Pro · 3 Meta Aria · 4 Ray-Ban Meta · 5 HoloLens · 6 Generic AR · 7 Other XR · 8 None. Use filters: [] for an open study, or ask the /prolific-beta-skills:recommend-study-filters skill to build one.

_{The head-mounted-devices filter — recruiting only AR / smart-glasses owners.}

Customize the ask. Edit request in config.yaml — the prompt text, the glasses dropdown, upload rules (accepted_file_types, max_file_size_mb), and the study block (reward, places, time estimate, filters). Here's the resulting task page:

_{What a participant sees — instructions, video upload, and the glasses question, all generated from config.yaml.}

② Watch live

python dashboard.py                       # serve at http://127.0.0.1:8050
python dashboard.py --port 9000           # different port
python dashboard.py --interval 3          # feed/demographics refresh (default 5s)
python dashboard.py --video-interval 60   # video sync cadence (default 90s)
python dashboard.py --no-videos           # counts + demographics only
python dashboard.py --study <id>          # a specific study (default: prolific_state.json)

A progress bar toward total_available_places, status counts (approved / awaiting review / active / returned …), and a live feed where each row carries the participant's video (click to play), glasses, and age / gender / country.

Data	Source	Refresh
status / counts / feed	GET /studies/{id}/, /submissions/counts/, /submissions/	every --interval (≈5s)
age / gender / location	GET /studies/{id}/export/ (demographics CSV)	every --interval (≈5s)
uploaded video + glasses	POST /data-collection/collections/{id}/export (batch zip)	every --video-interval (≈90s)

Videos sync on a slower background loop — Prolific only exposes uploads via that batch export — and cache locally, so they land a beat after their row ("video syncing…" until then) and an idle study costs nothing. For large studies, raise --video-interval or use --no-videos.

Caution: the dashboard shows participant videos, age, and location. It binds to 127.0.0.1 (your machine only) — don't pass --host 0.0.0.0 unless you mean to expose that data to your whole network.

③ Review

python3 review-app/server.py      # then open http://localhost:8000

Watch each clip, see participant ID + demographics + glasses, add notes, then Copy selected IDs or Export selected as CSV. Details: review-app/README.md.

④ Reward

Pay a bonus and/or message your picks — config-driven via bonus_message.yaml (study id, amount, the IDs you copied from the review app, and the message body):

python send_bonus_message.py --dry-run     # verify + preview only; sends nothing
python send_bonus_message.py               # set up bonus, confirm, then pay + message
python send_bonus_message.py --no-bonus    # message only
python send_bonus_message.py --no-message  # bonus only

It verifies every ID, prints a plan (subtotal + fees), sets up an unpaid bonus, and asks you to confirm before charging.

⚠️ Not idempotent — re-running pays participants again. Always start with --dry-run, and let the confirmation prompt be your safety check.

Where videos land

After results, look in ./results/:

results/collection-export-.../
├── responses.jsonl   # one record per submission (video file + glasses choice)
├── collection.json   # maps instruction IDs → labels
└── files/            # the uploaded videos (.mp4, .mov, …)

This — plus prolific_state.json and review-app/*.json — is git-ignored. It's participant video and demographics; never commit it.

End-to-end flow

config.yaml ──> create ──> launch ─────────────► participants record + upload
                  │                                        │
                  ▼                                        ▼
          prolific_state.json                    dashboard.py (watch live)
                  │                                        │
                  ▼                                        ▼
              results ──► review-app/ (curate, pick IDs) ──► bonus_message.yaml
                                                            │
                                                            ▼
                                              send_bonus_message.py (pay + message)

---

Contributing

Issues and pull requests welcome.

Important Notice

Provided as-is for educational and research purposes only. 🔬 Beta — may contain bugs · 📚 not actively maintained · ⚖️ test thoroughly before any production use.