Self-hostable, open-source media review platform. A collaborative alternative to Frame.io.
FreeFrame gives production houses and creative teams a self-hosted platform for reviewing video, image, and audio assets with frame-accurate commenting, annotations, and approval workflows. Your media stays on your infrastructure.
- Video review with HLS adaptive streaming and frame-accurate timecoded comments
- Image and audio review with annotations and waveform visualization
- Drawing annotations on any frame using canvas tools
- Threaded comments with mentions, reactions, and attachments
- Approval workflows with per-reviewer status tracking
- Version management to compare iterations side-by-side
- Folder organization within projects
- Team collaboration with role-based permissions (org, team, project levels)
- Share links for external reviewers (password-protected, expiring)
- Guest commenting via share links (no account required)
- Due date tracking with email reminders
- Real-time updates via Server-Sent Events
- Self-hosted with Docker Compose — runs on any server or cloud VM
Prerequisites: Docker and Docker Compose
git clone https://github.com/Techiebutler/freeframe.git
cd freeframe
cp .env.example .env
docker compose -f docker-compose.dev.yml up --buildOpen http://localhost:3000 to access FreeFrame. The first user to sign up becomes the super admin.
Services running in dev:
| Service | URL |
|---|---|
| Frontend | http://localhost:3000 |
| API | http://localhost:8000 |
| API Docs | http://localhost:8000/docs |
| MinIO Console | http://localhost:9001 |
cp .env.example .env.prod
# Edit .env.prod — set your credentials, S3, email config
# For SSL: also set DOMAIN and ACME_EMAIL (Traefik auto-provisions Let's Encrypt certs)
docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --buildFor the full guide including SSL setup, bring-your-own infrastructure (external database, Redis, S3, SMTP), scaling, and troubleshooting, see:
┌──────────────┐
│ Traefik │
│ :80/:443 │
└──────┬───────┘
│
┌───────────┴───────────┐
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Next.js │ │ FastAPI │
│ Frontend │ │ Backend │
└─────────────┘ └──────┬───────┘
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────────┐
│ PostgreSQL │ │ Redis │ │ S3 Storage │
│ │ │ │ │ (AWS/R2/MinIO) │
└───────────┘ └─────┬─────┘ └───────────────┘
│
┌──────────┴──────────┐
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Celery │ │ Celery │
│ Transcoder │ │ Email │
└─────────────┘ └─────────────┘
| Component | Technology |
|---|---|
| Frontend | Next.js 14, React 18, Tailwind CSS, Zustand |
| Backend | FastAPI, SQLAlchemy, Pydantic |
| Database | PostgreSQL 15 |
| Queue | Celery + Redis |
| Transcoding | FFmpeg (multi-bitrate HLS) |
| Storage | Any S3-compatible (AWS, R2, B2, MinIO) |
| Proxy | Traefik (auto SSL via Let's Encrypt) |
| Auth | JWT + magic code email login |
| Guide | Description |
|---|---|
| Production Deployment | SSL, bring-your-own infra, scaling, troubleshooting |
| Architecture | System design, data flow, media pipeline, permissions |
| Contributing | Dev setup, testing, code style, PR process |
| Environment Variables | Full config reference with comments |
We welcome contributions! Please read our Contributing Guide to get started.
MIT License — see LICENSE for details.
A project by Techiebutler
Have questions? Need help?
Email: support@techiebutler.com
Star the repo if FreeFrame is useful to you!