OpenStory takes a script and produces a sequence of AI-generated frames — images, motion video, audio — with consistent style across every scene. Teams collaborate on shared libraries of characters, locations, and visual styles, and the platform handles the heavy lifting of prompt engineering, generation, and compositing.
Features
- Script analysis — paste a script and get an automatic scene breakdown with camera angles, mood treatments, and continuity tracking
- AI image generation — generate scene images via Fal.ai with multiple model options
- Image-to-video motion — turn still frames into motion video clips
- Publish to social (optional) — with your own Upload-Post key, post a finished render to TikTok, Instagram, YouTube, LinkedIn, X and more
- Style consistency — characters, locations, color palettes, and lighting carry across scenes automatically
- Team workspaces (coming soon) — shared libraries of styles, characters, VFX, and audio
- Passkey authentication — passwordless sign-in via Better Auth
- Edge deployment — runs on Cloudflare Workers with global CDN
Tech Stack
See AGENTS.md for full architecture documentation, server handler patterns, workflow patterns, and React conventions.
Prerequisites
That's it. No Docker, no external database, no Cloudflare account — local dev runs the full stack (D1, R2, Workflows, Durable Objects, email) inside Workerd via Miniflare.
Quick Start
git clone https://github.com/openstory-so/openstory.git
cd openstory
bun install
bun dev
Open http://localhost:3000.
bun dev does everything: it generates .env.local (with auth/encryption secrets) on first run, migrates and seeds the local database, and starts the dev server.
To use AI generation features you need two API keys — run bun setup to add them interactively, or paste them into .env.local:
FAL_KEY — fal.ai for image, video & audio generationOPENROUTER_KEY — OpenRouter for LLM script analysis
See .env.example for all optional configuration (Google OAuth, Stripe, PostHog, remote R2).
Scripts
Development
| Command | Description |
|---|
bun dev | Bootstrap env, migrate + seed DB, start dev server |
bun setup | Interactive setup — add AI keys (--prod for deployments) |
bun tunnel:provision | Optional: 10 random public HTTPS names for ports 3000–3009 |
bun tunnel | Print this laptop's hostname map |
bun storybook | Start Storybook on port 6006 |
Quality
| Command | Description |
|---|
bun lint | Lint with oxlint (type-aware) |
bun lint:fix | Lint and auto-fix |
bun format | Format with oxfmt |
bun format:check | Check formatting without writing |
bun typecheck | Type-check with tsgo |
bun dead-code | Find unused exports with Knip |
Testing
| Command | Description |
|---|
bun run test | Run unit tests (Vitest) |
bun test:watch | Run tests in watch mode |
bun test:coverage | Run tests with coverage |
bun test:e2e | Run Playwright end-to-end tests |
bun test:e2e:ui | Run Playwright with interactive UI |
Database
| Command | Description |
|---|
bun db:generate | Generate migrations from schema changes |
bun db:migrate:local | Apply migrations (also runs as part of bun dev) |
bun db:studio:local | Open Drizzle Studio against the local database |
Build & Deploy
| Command | Description |
|---|
bun run build | Build for production (note: not bun build) |
bun setup --prod | Interactive production setup + deploy |
bun cf:deploy:prd | Manual production deploy (build → migrate → deploy) |
Stitch
The theatre player lives in packages/stitch and publishes as @openstory/stitch.
Run a local cut with npx. It prints an http://127.0.0.1 URL, opens that page, and runs until Ctrl+C.
npx @openstory/stitch --music score.mp3 shot.mp4
Install the OpenStory plugin for the agent skills. That install includes create-style, create-sequence, and stitch (/stitch). npx @openstory/stitch skill copies /stitch and stitch-player, the contract for embedding the React player. The plugin does not include stitch-player.
npx skills add openstory-so/skills
Grok, Claude Code, Codex, and the ChatGPT desktop app can add openstory-so/skills as a marketplace and install the OpenStory plugin. The per-client commands are in that repo.
The flags and the player API are in packages/stitch/README.md. That page is also in 中文, français, and español.
Project Structure
src/
components/ # React UI components (shadcn/ui based)
functions/ # Server functions (all business logic endpoints)
lib/ # Shared utilities, services, types
ai/ # AI model configs and prompt schemas
db/ # Database schema and clients (Drizzle)
services/ # Core business services
workflows/ # Cloudflare Workflows durable definitions
routes/ # TanStack Router file-based routes
api/ # Webhooks: workflows and auth only
_app/ # App shell (anonymous-browsable; actions gated behind login)
e2e/ # Playwright end-to-end tests
packages/stitch/ # Theatre player, the stitch command, and the stitch skills
scripts/ # CLI utilities and setup
See AGENTS.md for detailed architecture, data model, server handler patterns, and code conventions.
Deployment
Cloudflare Workers — edge runtime, R2 storage, D1 database, global CDN.
The deploy button clones the repo into your Cloudflare account, provisions the resources declared in wrangler.jsonc, and sets up CI. For a guided setup from your own clone, run bun setup --prod.
CI/CD: Cloudflare Workers Builds auto-deploys on push to main — the same mechanism deploy-button clones use. Pull requests get GitHub Actions preview deployments with dedicated D1 databases.
See the Platform & Deployment section in AGENTS.md for environment variable configuration and platform detection.
Contributing
We'd love your help building OpenStory! Whether it's fixing a bug, adding a feature, improving docs, or just sharing ideas — all contributions are welcome. Check out the issues labeled good first issue for a great place to start.
Read CONTRIBUTING.md for setup instructions, branch naming, code quality, and the pull request process.
License
MIT
