A web-based data entry form for World Bird Sanctuary's ethogram observations. This tool helps citizen scientists record Sayyida's behaviors during live Twitch streams or when reviewing recorded videos (VODs).
Current deployment: https://wbs-ethogram-form.vercel.app/
- Live streams & recorded video: Record observations while watching the live Twitch stream or reviewing a recording (VOD).
Time Entry: Always use the timestamp displayed in the top-left corner of the video. The video shows WBS time (America/Chicago, Central Time).
-
Flexible Time Ranges: Observe for any duration from 5 minutes to 1 hour
- Select any start and end time
- Automatically generates 5-minute interval slots
- Times displayed in friendly 12-hour format (e.g., "3:05 PM")
-
Autosave Protection: Your work is automatically saved
- Form data saved to your browser as you type
- Draft recovery if you accidentally close the tab
- Clear draft button when you're done
-
Smart Validation: Catches errors before you submit
- Inline error messages appear as you fill out the form
- Auto-scrolls to first error on submit
- Required fields clearly marked
- Observer name validation supports Discord/Twitch usernames and full names
- Copy-to-next validates before copying to prevent bad data
-
Structured Data Entry: Standardized options reduce errors
- Autocomplete perch location dropdown (type to filter)
- Interactive perch diagram map (click Map button to view)
- Behavior-specific interaction dropdowns
- "Other" text fields when you need them
- Notes field for additional context
- Copy-to-next button to duplicate observations across time slots
-
Easy Submission: Multiple ways to get your data to WBS
- Automatic: Click submit and your observation is sent directly to WBS
- Share via email: Send a copy to yourself or others after submission
- Download Excel: Download a local copy for your records
- Status tracking: Real-time feedback (submitting, success, or error)
- Error recovery: Retry button for temporary failures, local download fallback
When certain behaviors are selected, additional structured fields appear:
-
Interacting with Inanimate Object: Select object type from dropdown (newspaper, rope ball, plastic ball, rubber duck, wooden blocks, camera, plant, stump, perch, or other). If you select "other", a text field appears where you can type what the object is.
-
Interacting with Other Animal: Two dropdowns appear:
- Animal type: Adult/juvenile aviary occupant, insect within aviary, potential prey animal within aviary, potential prey item outside aviary, same species outside aviary, potential predator outside aviary, or other
- Interaction type: Watching, preening/grooming, feeding, playing, non-aggressive biting, non-aggressive foot grabbing, or other
For both fields, selecting "other" reveals a text field where you can specify the custom value.
-
Choose your observation mode: Are you watching the live stream or reviewing a recorded video?
-
Enter your information:
- Observer name (your Discord/Twitch username or full name)
- Date of observation
- Start and end times for your observation session
-
Record behaviors: For each 5-minute time slot:
- Select the behavior you observed
- Add location if required (perch number or "Ground")
- For object/animal interactions, select from the dropdown options
- Add notes if needed
- Use "Copy to next" to quickly duplicate observations across time slots
-
Submit: Click the "Submit Observation" button
- The form validates all required fields
- Your observation is automatically sent to WBS
-
After submission:
- Success: Download a copy or share via email to yourself/others
- Error: Retry the submission or download locally as a fallback
Your work is automatically saved as you type, so don't worry if you need to take a break!
- Before submission: Data is saved to your browser's localStorage as you type (autosave)
- On submission: Observations are sent to the WBS backend API and stored securely
- What's stored: Observer name, date, times, behaviors, locations, and notes
- No account required: Anonymous submissions are supported
- No tracking or analytics: We don't track your browsing behavior
The form outputs structured JSON data:
{
"metadata": {
"observerName": "YourDiscordName",
"date": "2025-11-20",
"startTime": "15:00",
"endTime": "15:30",
"aviary": "Sayyida's Cove",
"patient": "Sayyida",
"mode": "live"
},
"observations": {
"15:00": {
"behavior": "resting_alert",
"location": "12",
"notes": "",
"object": "",
"objectOther": "",
"objectInteractionType": "",
"objectInteractionTypeOther": "",
"animal": "",
"animalOther": "",
"animalInteractionType": "",
"animalInteractionTypeOther": "",
"description": ""
},
"15:05": {
"behavior": "interacting_object",
"location": "12",
"notes": "Playing with newspaper",
"object": "newspaper",
"objectOther": "",
"objectInteractionType": "biting",
"objectInteractionTypeOther": "",
"animal": "",
"animalOther": "",
"animalInteractionType": "",
"animalInteractionTypeOther": "",
"description": ""
}
},
"submittedAt": "2025-11-20T15:32:00.000Z"
}The per-slot field list is defined canonically by
createEmptyObservation()insrc/services/formStateManager.jsβ the example above is illustrative.
# Clone the repository
git clone https://github.com/iboughtamouse/wbs-ethogram-form.git
cd wbs-ethogram-form
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env
# Edit .env and set VITE_WBS_EMAIL to your test email
# Start development server
npm run dev
# Run tests
npm testThe application requires the following environment variables:
-
VITE_WBS_EMAIL- Email address to receive observation submissions- Development: Set to your test email address
- Production: Configure in Vercel with the WBS research email
-
VITE_API_BASE_URL- Backend API URL- Development: Point to local or deployed backend (e.g.,
http://localhost:3000orhttps://your-app.up.railway.app) - Production: Configure in Vercel with the production API URL
- Development: Point to local or deployed backend (e.g.,
Interested in contributing or learning more? Check out:
- ARCHITECTURE.md - System architecture, component structure, and data flow
- DEVELOPMENT.md - Technical setup, development workflow, and testing
- CONTRIBUTING.md - How to contribute to this project
Recently Completed:
- Backend API integration β (November 2025)
- Email submission (auto-sends Excel to WBS) β (November 2025)
- Share observation via email β (November 2025)
- Copy-to-next validation β (November 2025)
- Excel file export β (November 2025)
- Accessible loading indicators β (November 2025)
Upcoming Features:
- Discord OAuth authentication
- Extended observation periods (24+ hours)
- Data aggregation & analysis tools
- Inter-rater reliability calculations
MIT License - Feel free to use and modify for your organization's needs.
Built for the World Bird Sanctuary community and the amazing citizen scientists who observe Sayyida!