What is FreeFrame?

FreeFrame is a self-hosted platform for reviewing media files. Production houses and creative teams use it to add frame-accurate timecoded comments on video, images, and audio. It supports threaded discussions with mentions and reactions, drawing annotations on frames, and approval workflows tracking reviewer status. Users can compare versions side-by-side or with a wipe slider, export comments to editing software formats, share password-protected links for guest reviewers, and apply custom branding across the interface. The stack runs on Docker Compose with Next.js, FastAPI, PostgreSQL, Redis, Celery workers, and S3-compatible storage. Authentication relies on JWT with emailed magic codes. Licensed under MIT with active development.

Should you self-host FreeFrame?

FreeFrame scores 51/100 on selfhost.directory (how scoring works) and ranks #2 of 4 in Media. It has 241 GitHub stars.

It shipped 10 stable releases in the past year. The latest, v1.21.0, came out on 25 October 2026. New versions land roughly every 2 days.

Setup is advanced: plan for several services and some ongoing maintenance. It is MIT-licensed and written mostly in Typescript.

Its closest alternative on selfhost.directory is Shumai (47/100, 236 stars). FreeFrame scores higher overall. See FreeFrame vs Shumai side by side.

Features

Approval Workflows
Drawing annotations
Due date tracking
Folder Organization
Frame-accurate video review
Image and audio review
NLE comment export
Real-time updates
Role-based permissions
Share links for external reviewers
Social Preview
Threaded comments
Version compare
White-label branding

How to configure FreeFrame

ACCESS_TOKEN_EXPIRE_MINUTES15Access token expiry in minutes
Access token expiry in minutes
ACME_EMAILadmin@your-domain.comEmail for Let's Encrypt certificates
Email for Let's Encrypt certificates
API_INTERNAL_URLhttp://api:8000Internal API URL for server-to-server calls
Internal API URL for server-to-server calls
API_WORKERS4Gunicorn worker processes (production)
Gunicorn worker processes (production)
CORS_ALLOW_ORIGINSExtra CORS origins, comma-separated
Extra CORS origins, comma-separated
DATABASE_URLpostgresql://freeframe:freeframe@postgres:5432/freeframePostgreSQL connection URL
PostgreSQL connection URL
DOMAINyour-domain.comDomain name for SSL
Domain name for SSL
FRONTEND_URLhttp://localhost:3000Frontend URL with https:// for production
Frontend URL with https:// for production
JWT_ALGORITHMHS256JWT algorithm
JWT algorithm
JWT_SECRETchange-me-to-a-secure-random-stringJWT signing secret (required for production)
JWT signing secret (required for production)
MAIL_FROM_ADDRESSnoreply@example.comFrom email address
From email address
MAIL_PROVIDERsmtpEmail provider: smtp or ses
Email provider: smtp or ses
values: smtp, ses
NEXT_PUBLIC_API_URLhttp://localhost:8000Browser-facing API URL
Browser-facing API URL
POSTGRES_DBfreeframePostgreSQL database name
PostgreSQL database name
POSTGRES_PASSWORDfreeframePostgreSQL password
PostgreSQL password
POSTGRES_USERfreeframePostgreSQL username
PostgreSQL username
REDIS_PASSWORDRedis password (optional)
Redis password (optional)
REDIS_URLredis://redis:6379/0Redis connection URL
Redis connection URL
REFRESH_TOKEN_EXPIRE_DAYS7Refresh token expiry in days
Refresh token expiry in days
S3_ACCESS_KEYminioadminS3 access key
S3 access key
S3_BUCKETfreeframeS3 bucket name
S3 bucket name
S3_ENDPOINThttp://minio:9000S3 endpoint URL (required for non-AWS)
S3 endpoint URL (required for non-AWS)
S3_PUBLIC_ENDPOINTBrowser-reachable S3 endpoint for presigned URLs
Browser-reachable S3 endpoint for presigned URLs
S3_REGIONus-east-1S3 region
S3 region
S3_SECRET_KEYminioadminS3 secret key
S3 secret key
S3_STORAGEminioStorage backend: 's3' for AWS S3, 'minio' for other S3-compatible
Storage backend: 's3' for AWS S3, 'minio' for other S3-compatible
values: s3, minio
SMTP_HOSTsmtp.example.comSMTP server host
SMTP server host
SMTP_PASSWORDSMTP password
SMTP password
SMTP_PORT587SMTP server port
SMTP server port
SMTP_USERSMTP username
SMTP username
SMTP_USE_TLStrueUse TLS for SMTP
Use TLS for SMTP
values: true, false
TRANSCODER_QUALITIES1080p,720p,360pHLS quality ladder rungs
HLS quality ladder rungs
values: 2160p, 1080p, 720p, 360p
TRANSCODING_CONCURRENCY2Parallel video transcoding jobs
Parallel video transcoding jobs