KeyFrame | A Lightweight Slide-Show Generation Platform

KeyFrame is an agentic AI slideshow generator. Submit a prompt + style → get back a ~1 min video with AI images, voiceover, and captions for ~$0.05. The pipeline runs as a state machine with four named agents: The Watchman (pre-flight validation), The Director (script + visual bible), The Continuity Artist (image generation with visual consistency), and The Auditor (output validation with retry).

If generation fails, the free plans for Redis or Postgres may have expired. The community tab shows videos generated by other users.

Here it is: https://keyframe-frontend-production.up.railway.app/

Tech Stack

Frontend: React, Next.js, HTML, CSS, JavaScript, TypeScript

Backend: Redis, PostgrSQL, OpenAI, Flux-Schnell, Amazon Polly, FFMPEG

Dev Ops: Docker, Railway (all three services hosted on Railway)

Backend (Setup)

1) Prerequisites

• Install Node.js (v18+) and Python (3.10+)
• Docker (optional but recommended) or run Redis and Postgres locally
• FFmpeg installed and configured (see FFmpeg section below)
• Create .env files in backend/api/ and backend/worker/ (see templates below)
• Install Node deps in backend/api and Python deps in backend/worker

No extra pip installs needed beyond requirements.txt — all dependencies (celery, openai, boto3, mutagen, psycopg2-binary, python-dotenv, redis, requests) are already listed.

2) .env files

There are two separate .env files — one for the API, one for the worker. Do not use the same file for both.

backend/api/.env

REDIS_URL=redis://localhost:6379
DATABASE_URL=postgresql://keyframe_user:password@localhost:5432/keyframe_db
PORT=3002
ADMIN_PASSWORD=your-admin-password
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_ACCESS_KEY_ID=
CLOUDFLARE_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=
R2_PUBLIC_DOMAIN=

backend/worker/.env

# Redis (must match the API's REDIS_URL — Celery uses this as both broker and result backend)
REDIS_URL=redis://localhost:6379

# Database
DATABASE_URL=postgresql://keyframe_user:password@localhost:5432/keyframe_db

# Third-party API keys
OPENAI_API_KEY=
NEBIUS_API_KEY=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=us-east-1

# Cloudflare R2 (for video/thumbnail storage)
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_ACCESS_KEY_ID=
CLOUDFLARE_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=
R2_PUBLIC_DOMAIN=

# FFmpeg paths (optional — overrides the default bin/ fallback)
FFMPEG_PATH=
FFPROBE_PATH=

Note: FFmpeg path is configurable via FFMPEG_PATH and FFPROBE_PATH env vars (see FFmpeg section below). If these are not set, the worker falls back to <repo-root>/bin/ffmpeg.exe.

3) FFmpeg (Windows guidance)

1. Download a Windows build from https://www.gyan.dev/ffmpeg/builds/ (get the "essentials" release build)
2. Extract and copy ffmpeg.exe and ffprobe.exe into a bin/ folder at the repository root:
3. Verify: ./bin/ffmpeg.exe -version

Windows Smart App Control / AppLocker note (I had this problem)

If you get [WinError 4551] An Application Control policy has blocked this file when the worker tries to run FFmpeg, Windows Smart App Control is blocking the subprocess. Fix:

• Go to Settings → Windows Security → App & Browser Control → Smart App Control and set it to Off, then restart.
• If you're on a managed/enterprise machine, ask IT to allowlist the FFmpeg binary.

4) Install & run

Backend API

cd backend/api
npm install       # skip if node_modules already exists
node index.js     # PORT is read from backend/api/.env (default 3001)

Python worker (Windows recommended steps)

cd backend/worker
python -m venv .venv            # skip if .venv already exists
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt # skip if already installed
# Run Celery worker (Windows: --pool=solo is required)
celery -A app worker --loglevel=info --pool=solo

REDIS_URL is loaded automatically from backend/worker/.env via python-dotenv.

Frontend (Setup)

1) Prereqs

• Node.js v18+ (recommended)
• npm (or pnpm/yarn) installed

Install dependencies and run the dev server:

cd frontend
npm install       # skip if node_modules already exists
npm run dev

The dev server runs on http://localhost:3000 by default.

Create frontend/.env.local

NEXT_PUBLIC_BACKEND_URL=http://localhost:3002
BACKEND_URL=http://localhost:3002
ADMIN_PASSWORD=your-admin-password

Note: ADMIN_PASSWORD has no NEXT_PUBLIC_

Developed by the Kushagra Katiyar