OpenUserStudyKit is a lightweight toolkit for running small user studies. It provides a static demo frontend together with simple options for collecting results.

简体中文

Live demo: https://fusheng-ji.github.io/OpenUserStudyKit/

1. Clone the repo:

git clone https://github.com/fusheng-ji/OpenUserStudyKit.git
cd OpenUserStudyKit

1. Generate the video list and start the demo:

python generate.py --all
./start_local_server.sh
# open http://localhost:8000

Use a local HTTP server — opening index.html via file:// may break loading static/videos.json.

• Static demo built with SurveyJS
• Video list generator (utils/generate_video_list.py)
• Each visitor receives a randomized video set.
• Refreshing the page yields a new randomized set.
• Data is saved to Google Sheets in real time when Apps Script is configured.
  • Optional Google Sheets collection via Apps Script or service account

Run the generator to produce static/videos.json. It maps tag → list of video paths. If no subdirectories exist, a single all tag is produced.

Examples:

# Generate using all videos (no sampling)
python generate.py --all

# Sample N videos per tag
python generate.py --num 8

After generating, open the demo and complete the questionnaire. Submissions are sent to a configured Apps Script URL or saved to localStorage in demo mode.

• index.html — demo entry
• static/ — JS, assets, example videos
  • static/videos.json — generated video list
• generate.py — wrapper for generator
• utils/generate_video_list.py — generator script
• start_local_server.sh — local HTTP server helper

Organize videos into subfolders under static/videos to enable tag-based sampling. Example layout:

static/videos/
  ├─ scenic/
  ├─ indoor/
  └─ outdoor/

The generator will output a JSON mapping tags to POSIX paths.

Two approaches are supported; details moved to the Deployment section below.

This project is a static website and can be deployed to GitHub Pages.

# Include all videos (recommended)
python generate_video_list.py --all

# Or specify videos per category
python generate_video_list.py --num 20

• videos.json contains the paths to available videos.
• Each visitor receives a randomized selection from these lists. The default is 10 videos per category.
• Adjust NUM_VIDEOS_PER_CATEGORY in static/js/index.js to change the per-user sample size.

1. Go to https://script.google.com/
2. Create a new project
3. Copy the contents of static/js/google-apps-script.js into the editor
4. Replace SPREADSHEET_ID with your Google Sheets ID (from the sheet URL)
5. Save the project and give it a name (e.g. "User Study Survey API")

1. Click Deploy > New deployment
2. Choose type: Web App
3. Configure:
   • Description: Survey Data Receiver
   • Execute as: Me
   • Who has access: Anyone
4. Deploy and copy the Web App URL — you'll use it in the frontend

In static/js/index.js set the GOOGLE_SCRIPT_URL constant to your deployed URL. For example:

const GOOGLE_SCRIPT_URL = 'https://script.google.com/macros/s/YOUR_SCRIPT_ID/exec';

1. Commit and push all changes to your repository
2. Open your repository on GitHub
3. Go to Settings > Pages
4. Under "Build and deployment" choose "Deploy from a branch"
5. Select branch main and folder / (root)
6. Save; after a few minutes the site will be available at https://<your-username>.github.io/<repo>/

# 1. Add changes
git add .

# 2. Commit
git commit -m "Deploy static survey website"

# 3. Push
git push origin main

# 4. Enable Pages in the repo settings as described above

• index.html — main page
• static/videos.json — generated video list (required)
• static/js/index.js — frontend survey logic. Configure GOOGLE_SCRIPT_URL in this file if you use Apps Script.
• static/videos/*.mp4 — video files (if you keep videos in the repo)

Adjust number of videos per user by editing static/js/index.js:

// Number of videos sampled per category per user
const NUM_VIDEOS_PER_CATEGORY = 10; // change as needed

./start_local_server.sh

python3 -m http.server 8000

Open http://localhost:8000 in your browser.

Note: In local/demo mode (no GOOGLE_SCRIPT_URL configured), submissions are saved to localStorage.

Two approaches for integrating with Google Sheets are supported:

• Apps Script Web App (easy): paste static/js/google-apps-script.js into Apps Script, set SPREADSHEET_ID, deploy as a Web App, and then set GOOGLE_SCRIPT_URL in static/js/index.js.
• Service Account (server-to-server): enable the Sheets API, create a service account, share the spreadsheet with the service account email, and use the Google API client on a server.

Security notes: never commit service account keys to the repo. Use environment variables, Secret Manager, or CI secrets instead. Prefer Apps Script when you want to avoid storing keys in a repo.

Submissions are saved to Google Sheets. Each row will contain per-category averages and a Raw_Data_JSON column with detailed per-video ratings.

Example columns include Timestamp, Name, Session ID, and Response Data (JSON).

JSON.parse(localStorage.getItem('survey_submissions'))

• Ensure static/videos.json exists and paths are correct
• Check video paths and file names
• Inspect browser console for errors

• Verify GOOGLE_SCRIPT_URL in static/js/index.js
• Verify Apps Script deployment and permissions
• Check network requests in browser dev tools

• Ensure index.html is in repo root
• Wait a few minutes for GitHub Pages to build
• Check Settings > Pages for status

# Regenerate the video list if videos changed
python generate_video_list.py --all

git add .
git commit -m "Update survey content"
git push origin main

# GitHub Pages will redeploy automatically (usually within a few minutes)

After deployment the demo will be available at your GitHub Pages URL, for example:

https://fusheng-ji.github.io/OpenUserStudyKit/

Share this link with participants.

OpenUserStudyKit is distributed under the permissive