{"id":50999785,"url":"https://github.com/eren23/openflipbook","last_synced_at":"2026-06-20T13:04:58.469Z","repository":{"id":353430430,"uuid":"1219379107","full_name":"eren23/openflipbook","owner":"eren23","description":"Open-source flipbook.page clone — every page is an AI-generated illustration, click anywhere to explore deeper. Next.js + FastAPI + Modal. BYO keys.","archived":false,"fork":false,"pushed_at":"2026-06-13T08:30:13.000Z","size":42710,"stargazers_count":151,"open_issues_count":0,"forks_count":38,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-13T10:14:39.140Z","etag":null,"topics":["ai-image-generation","byo-keys","fal-ai","fastapi","flipbook","gemini-api","generative-ai","infinite-canvas","ltx-video","modal","nano-banana","nextjs","openrouter","self-hosted","typescript","vision-model"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eren23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-23T20:19:44.000Z","updated_at":"2026-06-13T08:30:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eren23/openflipbook","commit_stats":null,"previous_names":["eren23/openflipbook"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/eren23/openflipbook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fopenflipbook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fopenflipbook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fopenflipbook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fopenflipbook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eren23","download_url":"https://codeload.github.com/eren23/openflipbook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eren23%2Fopenflipbook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34570576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-image-generation","byo-keys","fal-ai","fastapi","flipbook","gemini-api","generative-ai","infinite-canvas","ltx-video","modal","nano-banana","nextjs","openrouter","self-hosted","typescript","vision-model"],"created_at":"2026-06-20T13:04:57.910Z","updated_at":"2026-06-20T13:04:58.462Z","avatar_url":"https://github.com/eren23.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# openflipbook\n\n\u003e **An open-source [flipbook.page](https://flipbook.page) clone, image-is-the-UI.** Every page is an AI-generated illustration. Tap anywhere on the image and a vision model resolves what you tapped, turns it into the next page, and keeps going. Seed from a text query or drop in any image. Bring your own API keys; clone, run, hack.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/eren23/openflipbook?style=social)](https://github.com/eren23/openflipbook/stargazers)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-green.svg)](package.json)\n[![Next.js](https://img.shields.io/badge/Next.js-15-black.svg)](https://nextjs.org)\n[![FastAPI](https://img.shields.io/badge/FastAPI-Modal-009688.svg)](https://modal.com)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n## Demo\n\n![openflipbook demo — tap any region of an AI-generated page; a vision model resolves what you tapped and renders the next page](apps/web/public/demo.gif)\n\nSped up 4×: landing → `\"how does a steam engine work\"` deeplink → two click-to-explore hops. [Full-quality MP4 with audio](https://github.com/eren23/openflipbook/raw/main/apps/web/public/demo.mp4). Recorded with the Playwright driver under [`scripts/record-demo/`](scripts/record-demo/) — run `pnpm record-demo` to re-capture against your own stack.\n\n## Why this exists\n\n[flipbook.page](https://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/`.\n\n## TL;DR\n\n- **One image per page**, rendered by fal (default balanced tier: [`nano-banana-pro`](https://fal.ai/models/fal-ai/nano-banana-pro)). Text inside the page is pixels, not DOM.\n- **Click → next page.** [`google/gemini-3-flash-preview`](https://openrouter.ai/google/gemini-3-flash-preview) via OpenRouter resolves the clicked region to a phrase; the same model family plans the page with web-search grounding.\n- **Seed from your own image.** Upload / drag-and-drop works as a starting point.\n- **Optional animation toggle.**\n  - Default: one-shot 5s MP4 from `fal-ai/ltx-video/image-to-video`. Cheap (~$0.02/clip), no GPU on your side.\n  - Streaming: the same LTXF binary WebSocket protocol Flipbook uses, deployed to your own Modal account — true fragmented-MP4 streaming into a `\u003cvideo\u003e` tag via Media Source Extensions.\n- **Permalinks.** `/n/:id` hydrates from Mongo + R2 without regenerating.\n- **Pin a style.** Hit the 📌 on any page and every new page in the session inherits that look (palette, line work, perspective). Persists across reload.\n- **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.\n- **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.\n- **Time-scrubber (`T`).** Linear film-strip of every page in your trail; drag the scrubber to time-travel through your own exploration.\n- **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.\n- **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.\n- **BYO keys.** No hosted backend. Clone it, run it, pay your own bills.\n\n```\n   ┌────────────────────────┐                  ┌─────────────────────────┐\n   │  type query / drop img │                  │  illustrated page       │\n   └─────────┬──────────────┘                  └─────────┬───────────────┘\n             │                                           │ tap on a region\n             ▼                                           ▼\n    ┌───────────────────┐   plan page    ┌──────────────────────────┐\n    │  OpenRouter Gemini │ ─────────────▶ │  fal nano-banana-pro      │\n    │  3 Flash (+ search)│                │  renders labelled image   │\n    └───────────────────┘                └──────────────┬───────────┘\n             ▲                                          │\n             │  subject phrase                          │\n             │                                          ▼\n    ┌────────┴──────────┐    click +    ┌──────────────────────────┐\n    │ OpenRouter Gemini 3  image ◀── │ next page conditioning    │\n    │ Flash (VLM)          │               └──────────────────────────┘\n                                                       │\n                                                       ▼\n                               ┌────────────────────────────────────┐\n                               │  optional: Animate toggle          │\n                               │  ├─ default: fal-ai/ltx-video clip │\n                               │  └─ streaming: Modal LTX-2 via WS  │\n                               │     with custom LTXF fMP4 framing  │\n                               └────────────────────────────────────┘\n\n                            persistence: Cloudflare R2 + MongoDB\n```\n\n**Read the backstory:** [`docs/STORY.md`](docs/STORY.md) — what we hoped Flipbook would be, what it actually is, and how the internals look once you crack the bundle open.\n\n## Quickstart\n\nThe fastest path — Docker, local Mongo + blob storage, cloud AI (two keys):\n\n```bash\ngit clone https://github.com/eren23/openflipbook\ncd openflipbook\n\ncp .env.example .env          # fill FAL_KEY + OPENROUTER_API_KEY\nmake demo                     # → http://localhost:3000/play\n```\n\nThat's it. Mongo, Minio, backend, and web all come up wired together. Open [`/status`](http://localhost:3000/status) for a live env check. Full compose reference: [`docs/DOCKER.md`](docs/DOCKER.md).\n\n**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).\n\n**Without Docker:** see [`docs/LOCAL_DEV.md`](docs/LOCAL_DEV.md).\n\n### Hosted setup (Modal + R2)\n\nIf 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`](docs/BYO-KEYS.md).\n\n## What you need (local demo)\n\n| Service | Used for | Variable |\n|---|---|---|\n| [fal](https://fal.ai/dashboard/keys) | image gen + optional animate | `FAL_KEY` |\n| [OpenRouter](https://openrouter.ai/keys) | planning + click VLM + web search | `OPENROUTER_API_KEY` |\n\nMongo + blob storage run locally in Docker — no cloud accounts required for `make demo`.\n\n## What you need (hosted)\n\n| Service | Used for | Variable |\n|---|---|---|\n| [fal](https://fal.ai/dashboard/keys) | image gen (nano-banana) + optional animate fallback | `FAL_KEY` |\n| [OpenRouter](https://openrouter.ai/keys) | planning + click VLM + web search | `OPENROUTER_API_KEY` |\n| [Cloudflare R2](https://dash.cloudflare.com/?to=/:account/r2) | generated-image storage | `R2_*` + `R2_PUBLIC_BASE_URL` |\n| MongoDB | node graph + session metadata | `MONGODB_URI`, `MONGODB_DB` |\n| [Modal](https://modal.com) | Python backend host; optional GPU worker for streaming | `modal token new` |\n\nFull setup walkthrough: [`docs/BYO-KEYS.md`](docs/BYO-KEYS.md).\n\n## Repo layout\n\n```\napps/\n  web/                Next.js 15 app (landing, /play, /n/:id, /status)\n  modal-backend/      FastAPI — SSE page gen, click VLM, optional LTX GPU worker\npackages/\n  config/             Shared TS types (GenerateEvent, LTXStreamStartMessage, …)\ninfra/\n  MONGO.md            Document shape + hosting notes\ndocs/\n  STORY.md            What we hoped Flipbook was, vs. what it is\n  BYO-KEYS.md         Full credential walkthrough\n  DOCKER.md           Compose stack docs\n  LOCAL_DEV.md        Running without Docker\n```\n\n## Further reading\n\n- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — code layout, where things live, how the play surface is split into hooks vs components vs lib.\n- **[docs/STORY.md](docs/STORY.md)** — the backstory + reverse-engineered LTXF protocol.\n- **[docs/BYO-KEYS.md](docs/BYO-KEYS.md)** — credential + deploy walkthrough.\n- **[docs/DOCKER.md](docs/DOCKER.md)** — compose stack reference.\n- **[docs/LOCAL_DEV.md](docs/LOCAL_DEV.md)** — running without Docker.\n- **[infra/MONGO.md](infra/MONGO.md)** — document shape + index layout.\n\n## Contributing\n\nPRs welcome. See [`CONTRIBUTING.md`](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`](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © 2026 Eren Akbulut.\n\n## Credits\n\nThe original paradigm, `anchor_loop` trick, and LTX-2 streaming engine are the work of [Zain Shah](https://x.com/zan2434), [Eddie Jiao](https://x.com/eddiejiao_obj), and [Drew Carr](https://x.com/drewocarr) on Flipbook. This repo is an independent open-source re-implementation written from public bundle inspection — no Flipbook source code is used.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feren23%2Fopenflipbook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feren23%2Fopenflipbook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feren23%2Fopenflipbook/lists"}