Warqa · ورقة

Turn a PDF into an animated, narrated, interactive book — in Arabic, Darija, French and English, with any AI model.

ورقة is Arabic for “a sheet of paper”.

Start here · ابدأ من هنا · Commencer ici · Try it in your browser · Example lesson

Warqa reads a book, plans a series of short lessons, and writes each one as a sequence of beats: narration paired with visual changes that happen on the exact words that explain them. Quick checks and practice happen inside the picture. Learners can watch, listen, pause, answer, and switch language mid-lesson. The result is a small website that works offline: no server, no account.

PDF → read (Arabic repairs, OCR) → plan → storyboard → write beats → translate → narrate → QA → book

For teachers and parents

You don't need to know how to program:

1. In your browser: open the web app, paste a key from an AI service (the guide shows the cheap and free ones), and drop a PDF. Nothing to install; your books and key stay on your computer.

2. On your computer, every feature: download Warqa and double-click the launcher for Windows, Mac or Linux.

No PDF at hand? Use one of the sample PDFs: an Arabic maths chapter, a French science chapter, or an Arabic picture book.

The start-here guide walks you through your first book, in Arabic, French and English.

Related MCP server: interactive-edtech-mcp

What it does

• Any model, your choice. Claude, GPT, Gemini, Mistral, DeepSeek, Grok, anything on OpenRouter, any OpenAI-compatible server, or fully local with Ollama, LM Studio, llama.cpp or vLLM. Pick a model per role (planner, writer, translator, vision, judge). Models never write code or pixels: they fill a validated lesson format, problems go back to them for repair, and small models get a simpler format with cues placed automatically. → models

• Arabic first, Darija included.

  • Layout: right to left, mirroring what should mirror and keeping what shouldn't (number lines, maps, math). Math is written left to right inside Arabic text, as in Moroccan textbooks.

  • Answers: Arabic-Indic digits and decimal commas are accepted.

  • PDFs: garbled Arabic text is repaired, or sent to OCR.

  • Darija (ary) is a full book language, with its own player interface. → Arabic and Darija

• Any-to-any translation with a memory.

  • One lesson structure, one string table per language; translations keep every mark, answer box and formula.

  • A book-wide translation memory and glossary checks keep wording consistent across chapters.

  • Teachers review translations in the studio or in a spreadsheet, and their wording is never overwritten. → translation

• Teaching, not slides.

  • The scene persists across beats, and components are stateful: an equation morphs, a number line hops, a clock's hands turn, a map lights up a region.

  • Validators enforce pacing: a visual change per sentence, no empty openings, questions between ideas.

  • 25 components (math typeset with MathJax, maps down to the regions of a country, picture-book pages read word by word, timelines, concept maps…), plus third-party packs. → components · maps and math

• Quality you can check.

  • Headless QA of every beat.

  • A vision judge whose notes drive automatic rewrites (warqa improve).

  • Blind teacher panels whose scores go on the model leaderboard. → quality

• Voices.

  • Engines: Edge (free), Azure, OpenAI, ElevenLabs, Google, Gemini, or local voices through the optional Python worker.

  • Word times give exact cues and read-along highlighting. → voices

• Open and portable.

  • Apache-2.0. Books are folders of JSON you can diff and edit.

  • Exports: static site (installable, offline), zip, SCORM 1.2 (Moodle…), Anki, CSV, MP4 video. → exports

Try it as a developer

git clone https://github.com/Redouane-E/warqa && cd warqa
pnpm install && pnpm build
pnpm warqa preview examples/integers.warqa   # open http://127.0.0.1:8765/
pnpm studio                                  # the studio on http://127.0.0.1:5170/ (books in ./books)

Example books:

Make your own book

pnpm warqa init my-book --pdf textbook.pdf --langs ar,fr,en --audience "collège, 1ère année"
cd my-book
cp ../.env.example .env        # add one API key (or use Ollama: --preset local)
warqa ingest                    # read the PDF (text, Arabic repairs, OCR fallback, chapters)
warqa plan                      # draft the book plan → review plan.json
warqa plan --approve
warqa estimate                  # what it will cost with your models
warqa build --chapter ch01      # storyboard → write → translate → narrate
warqa improve --chapter ch01    # optional: a vision model judges each picture; weak beats are rewritten
warqa qa --chapter ch01 --shots # headless checks + screenshots
warqa review --lang ar          # translation review (or --export review.csv for a spreadsheet)
warqa preview                   # watch it
warqa export --zip --scorm --anki ar

Other entry points:

• Studio: the same in a browser. Upload a PDF, choose models, review the plan, build chapters, edit beats with a live preview, review translations, narrate and export.

• Coding agent: Warqa is also an MCP server (claude mcp add warqa -- node apps/mcp/dist/server.js). An agent can run the pipeline, or write lessons itself while Warqa validates and renders them. → agents

Repository

packages/i18n       UI catalogs (ar/ary/fr/en), number parsing, Arabic normalization, bidi helpers
packages/lesson     lesson format (Zod), compiler, validators, grading, components, packs, and the player
packages/pipeline   PDF ingest, model layer, stages, translation memory, maps, math, speech, QA, panels, exports
apps/cli            the `warqa` command
apps/studio         the studio (Hono + React)
apps/web            the studio in the browser, with no server (GitHub Pages)
apps/mcp            MCP server for coding agents
workers/py          optional Python worker: OCR, forced alignment, Arabic diacritics, local voices
launchers           one-click start for Windows, Mac and Linux
e2e · evals         Playwright tests (Chromium, Firefox, WebKit) · model evaluations and the leaderboard
examples            example books and a component pack

Development: pnpm build, pnpm test, pnpm e2e, pnpm lint.

Contributing

Contributions are welcome: code, translations of the interface, new components and packs, example books, bug reports from teachers. Start with CONTRIBUTING.md, follow the Code of Conduct, and see SUPPORT.md for questions. The status page lists known limits and ideas.

Credits and licence

Warqa is licensed under the Apache License 2.0. It builds on ideas and code from Papermorph (MIT): beats paired with narration marks, in-picture questions, first-try scoring and the delivery checks. Math is typeset with MathJax; maps use Natural Earth and geoBoundaries data. See THIRD_PARTY_NOTICES.md. Fonts are under the SIL Open Font License. The books you make are yours; respect the rights of the PDFs you use.