OpenStory

Transform scripts into styled video productions using AI.

OpenStory takes a script and produces a sequence of AI-generated frames — images, motion video, audio — with consistent style across every scene. Organizations 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
• Organization 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

Category	Tools
Runtime	Bun
Framework	TanStack Start + TanStack Router + Vite
Database	Drizzle ORM + Cloudflare D1 (SQLite)
AI	TanStack AI + Fal.ai + OpenRouter + PostHog (LLM observability)
Workflows	Cloudflare Workflows (durable execution)
Realtime	Cloudflare Durable Objects (SSE progress updates)
Storage	Cloudflare R2 (S3-compatible)
Auth	Better Auth
Styling	Tailwind v4 + shadcn/ui
Quality	oxlint + oxfmt + tsgo + Lefthook + Knip
Testing	Vitest + Playwright
Deployment	Cloudflare Workers

See AGENTS.md for full architecture documentation, server handler patterns, workflow patterns, and React conventions.

Prerequisites

• Bun >= 1.3.9 — install

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 generation
• OPENROUTER_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