🎬 Frame Note

A collaborative video annotation tool that lets you add comments and drawings to videos. Annotations sync across users via a shared database — without ever uploading the video itself.

✨ Features

• 📝 Time-based annotations — Add comments at specific timepoint. Comments can contain any attachments (images and PDF)

  • Select a timerange like below and comment

  • Or pick a timestamp and comment. You can add an attachment to any comment as shown below

• 🎨 Drawing overlay — Draw directly on video frames

• ✨ AI Visual Suggestions — Get creative ideas for memes, animations, and illustrations using Gemini AI (requires captions)

• 👥 Collaborative — Share annotations across team members.

• 🔒 Privacy-first — Videos stay local, only annotations are stored

• 🔗 Smart linking — Videos identified by content hash (same file = same annotations)

---

💡 How Video Identification Works

Videos are identified by their SHA-256 content hash, not filename. This means:

• ✅ Same video file → Same annotations (even on different machines)
• ✅ Renamed file → Still matches
• ❌ Re-encoded video → Different hash, won't match

---

🛠️ Tech Stack

Layer	Technology
Frontend	React 19, Vite, Fabric.js
Backend	Express, Node.js
Database	PostgreSQL
Runtime	Bun (frontend), Node (backend)

---

🚀 Local Development

Prerequisites

• Node.js v20+
• Bun (for frontend) — Install Bun
• PostgreSQL running locally (or via Docker)

1️⃣ Start the Database

# Option A: Use Docker (recommended)
POSTGRES_PORT=5432 docker-compose up -d postgres

# Option B: Use existing PostgreSQL
createdb frame_note
psql -d frame_note -f backend/src/db/schema.sql

2️⃣ Start the Backend

cd backend
npm install

# Create .env file from example
cp env.example .env

# Edit .env and add your Gemini API key
# GEMINI_API_KEY=your-api-key-here

npm run dev

The API runs at http://localhost:3000

Note: Get your Gemini API key from Google AI Studio

The server will show ✨ Gemini AI: Enabled when the API key is loaded correctly.

3️⃣ Start the Frontend

cd frontend
bun install
bun run dev

The app opens at http://localhost:5173

---

🐳 Production with Docker

Deploy everything with a single command:

docker compose up -d --build

This starts:

• 📦 PostgreSQL database with persistent volume
• 🚀 App server serving both API and frontend

Access the app at http://localhost:3000

Useful Commands

# View logs
docker compose logs -f

# Stop everything
docker compose down

# Reset database (⚠️ destroys data)
docker compose down -v
docker compose up -d --build

---

📁 Project Structure

frame-note/
├── frontend/           # React + Vite app
│   ├── components/     # UI components
│   ├── services/       # API client
│   └── utils/          # Helper functions
├── backend/            # Express API server
│   ├── src/
│   │   ├── routes/     # API endpoints
│   │   └── db/         # Database connection & schema
├── docker-compose.yml  # Production orchestration
└── Dockerfile          # Multi-stage build

---

🔧 Environment Variables

Variable	Default	Description
PORT	3000	Backend server port
DB_HOST	localhost	PostgreSQL host
DB_PORT	5432	PostgreSQL port
DB_NAME	frame_note	Database name
DB_USER	postgres	Database user
DB_PASSWORD	postgres	Database password
GEMINI_API_KEY	-	Google Gemini API key (for AI features)

---

📡 API Endpoints

Method	Endpoint	Description
POST	/api/users	Create user
GET	/api/users/:id	Get user
PATCH	/api/users/:id	Update user
GET	/api/annotations/video/:videoId	Get video annotations
POST	/api/annotations	Create annotation
PATCH	/api/annotations/:id	Update annotation
DELETE	/api/annotations/:id	Delete annotation
GET	/api/annotations/export/:videoId	Export as JSON
POST	/api/annotations/import	Import from JSON
POST	/api/suggestions	Get AI visual suggestions

---

📄 License

MIT