openflipbook

openflipbook

Explore illustrated worlds. Keep the places you create. Start with a map or a prompt, enter a place, and return to its saved view. Edit names and canonical references, branch your world, and share a read-only journey. Open source and self-hosted, inspired by flipbook.page.

Demo

World walkthrough | Place identity and its limits | H3 Max vs LTX transition pilot

Automatic exterior arrivals: implementation and pending visual audit

This is a saved product output, not a promise that every newly generated viewpoint will match it. Revisits retrieve saved images; new perspectives can still drift. The walkthrough separates persistence, generation accuracy, and animated transitions.

Why this exists

flipbook.page is fun but closed. I wanted the same loop — one image per page, tap to explore — on a stack I actually own: my keys, my storage, my backend. This is that, MIT-licensed, with every piece swappable behind small provider interfaces in apps/modal-backend/providers/.

TL;DR

• One image per page, rendered by swappable image providers. Balanced fresh maps currently use Seedream; entered scenes have their own edit-model route. See image tiers and model routing. Text inside the page is pixels, not DOM.
• Click → next page. A vision model resolves the clicked region; a planner turns it into the next image request. Current defaults live in the LLM provider.
• Seed from your own image. Upload / drag-and-drop works as a starting point.
• Optional animation toggle.
  • Ambient animation: a one-shot MP4; no GPU required on your side. Arrival transitions use a separate first-and-last-frame model slot. Both cost money when generated, but saved arrival clips replay without another model call.
  • Streaming: the same LTXF binary WebSocket protocol Flipbook uses, deployed to your own Modal account — true fragmented-MP4 streaming into a <video> tag via Media Source Extensions.
• Permalinks. /n/:id hydrates from Mongo + R2 without regenerating.
• Embeddable worlds. Publish a world (right-click → Publish) and it becomes frameable: /embed/:sessionId is a read-only interactive viewer — tap the dots to walk the already-generated pages, zero model calls, works in any iframe. Platforms that speak oEmbed unfurl /n/ links into it automatically; everyone else gets the one-line <script src=".../embed.js"> + <div data-openflipbook="..."> wrapper. Deployer recipes (Discourse, the oEmbed registry, Iframely/Notion) live in docs/EMBEDDING.md.
• Pin a style. Carry a saved style reference into subsequent generation requests. The pin persists across reload; the model can still fail to match it.
• Place Inspector. Rename mapped places, preserve old names as aliases, lock identity metadata, choose a canonical image crop, and revisit saved views. See the identity contract.
• Citations. When the planner runs with :online, the source URLs ride through to a tiny 📎 chip in the corner of the page — one click, you can see what it actually read.
• Shift-drag to circle a region. Freehand stroke on the image, release, and the next page focuses on what you scribbled. Same VLM as the click path, just more pointed.
• Time-scrubber (T). Linear film-strip of every page in your trail; drag the scrubber to time-travel through your own exploration.
• Faster clicks. As soon as a page renders, the VLM precomputes the 3–4 most clickable regions in the background, so most taps skip the resolve round-trip.
• Progressive render. On the balanced/pro tiers the cheap fast model paints a draft in parallel, so you get something on screen seconds before the final lands. Toggle off with PROGRESSIVE_DRAFT=false if you’d rather save the extra fal call.
• Edit a page in place. Describe a change and the page revises itself instead of spawning a child. With EDIT_REGION on you drag the exact region, the mask rides the edit, and a judge scores the result — verdict chip + one-click revert included.
• World Mode (on by default). Pages are places: tap a glowing region to enter it as a scene, go deeper, ascend back out, or pan to a logical neighbour — all rungs on one metric scale ladder. Every page gets its entities and camera extracted into a live geo overlay and a persistent world map, so revisiting a place brings back that place. WORLD_MODE=false restores the classic explainer flow, and each session has its own toggle.
• Critic loop. Critics score place, camera, and style and can request another attempt. Ordinary loops may keep a below-threshold best attempt. Experimental strict mode instead rejects failed outputs without changing the world, but its judges still have false positives; strict mode remains off by default.
• BYO keys. No hosted backend. Clone it, run it, pay your own bills.

   ┌────────────────────────┐                  ┌─────────────────────────┐
   │  type query / drop img │                  │  illustrated page       │
   └─────────┬──────────────┘                  └─────────┬───────────────┘
             │                                           │ tap on a region
             ▼                                           ▼
    ┌───────────────────┐   plan page    ┌──────────────────────────┐
    │ OpenRouter planner│ ─────────────▶ │ image provider / router  │
    │ + optional search │                │ renders labelled image  │
    └───────────────────┘                └──────────────┬───────────┘
             ▲                                          │
             │  subject phrase                          │
             │                                          ▼
    ┌────────┴──────────┐    click +    ┌──────────────────────────┐
    │ click vision model│ ◀── image ── │ next page conditioning    │
    │ + world context   │               └──────────────────────────┘
                                                       │
                                                       ▼
                               ┌────────────────────────────────────┐
                               │  optional: Animate toggle          │
                               │  ├─ default: fal MiniMax H3 clip   │
                               │  └─ streaming: Modal LTX-2 via WS  │
                               │     with custom LTXF fMP4 framing  │
                               └────────────────────────────────────┘

                            persistence: Cloudflare R2 + MongoDB

Read the backstory: docs/STORY.md — what we hoped Flipbook would be, what it actually is, and how the internals look once you crack the bundle open.

Quickstart

To test navigation without API keys or model charges, run make demo-mock with Docker. Its placeholder images test the plumbing, not visual quality.

The fastest path — Docker, local Mongo + blob storage, cloud AI (two keys):

git clone https://github.com/eren23/openflipbook
cd openflipbook

cp .env.example .env          # fill FAL_KEY + OPENROUTER_API_KEY
make demo                     # → http://localhost:3000/play

That’s it. Mongo, a local S3 store (RustFS), backend, and web all come up wired together. Open /status for a live env check. Full compose reference: docs/DOCKER.md.

The world stuff is the default now — make demo boots with World Mode + scale-ladder navigation on: taps enter places, you can go deeper, ascend back out, and pan to neighbours. WORLD_MODE=false make demo brings back the classic explainer stack, and make demo-world still works (it additionally pins the planner to Gemini).

Images-only cloud: make demo-local runs the planner + click VLM on local Ollama — only FAL_KEY needed (first run pulls multi-GB models; CPU-slow).

Without Docker: see docs/LOCAL_DEV.md.

Hosted setup (Modal + R2)

If you want to deploy the backend to Modal and store blobs on Cloudflare R2 instead of the local stack, you’ll also need Mongo/R2 credentials and a Modal token. Walkthrough: docs/BYO-KEYS.md.

What you need (local demo)

Mongo + blob storage run locally in Docker — no cloud accounts required for make demo.

What you need (hosted)

Full setup walkthrough: docs/BYO-KEYS.md.

Repo layout

apps/
  web/                Next.js 15 app (My Worlds, /play, /n/:id, /status)
  modal-backend/      FastAPI — SSE page gen, click VLM, optional LTX GPU worker
packages/
  config/             Shared TS types (GenerateEvent, LTXStreamStartMessage, …)
infra/
  MONGO.md            Document shape + hosting notes
docs/
  STORY.md            What we hoped Flipbook was, vs. what it is
  BYO-KEYS.md         Full credential walkthrough
  DOCKER.md           Compose stack docs
  LOCAL_DEV.md        Running without Docker

Further reading

• Creator workspace: saved-world library, reliable resume, private world/place notes, and browser-cookie access limits.
• Current roadmap and controllable-model report — priorities, tested evidence, model options, and decision gates for arrivals and spatial movement.
• docs/ARCHITECTURE.md — code layout, where things live, how the play surface is split into hooks vs components vs lib.
• docs/STORY.md — the backstory + reverse-engineered LTXF protocol.
• docs/BYO-KEYS.md — credential + deploy walkthrough.
• docs/DOCKER.md — compose stack reference.
• docs/LOCAL_DEV.md — running without Docker.
• docs/TESTING.md — the free gates + the paid eval benches (scenario lab, layout/style A/Bs, reconstruction bench).
• infra/MONGO.md — document shape + index layout.

Contributing

PRs welcome. See CONTRIBUTING.md for ground rules (BYO-keys stays BYO-keys, one image per page, no vendored Flipbook source) and local setup. Security issues: SECURITY.md.

License

MIT © 2026 Eren Akbulut.

Credits

The original paradigm, anchor_loop trick, and LTX-2 streaming engine are the work of Zain Shah, Eddie Jiao, and Drew Carr on Flipbook. This repo is an independent open-source re-implementation written from public bundle inspection — no Flipbook source code is used.