Warning: This project is under active development and has not been proofread against a printed Mushaf. Do not use the output for production or distribution without thorough verification.
A CLI tool that generates per-line and per-page PNG/WebP images of the Quran using QCF (Quran Complex Font) page fonts.
Black glyphs on transparent background — enabling dark/light theming via tint color in consuming apps.
Supports font versions V1 (1405H), V2 (1423H), and V4 (Tajweed with embedded colors).
bun installbun src/cli.tsPrompts for version, mode, width, page range, format, and markers. Downloads assets from GitHub releases if missing.
bun src/cli.ts [startPage] [endPage] [width] [mode] [v1|v2|v4] [no-markers] [webp] [bounds] [json] [quantize] [dark] [--ink <hex>] [--recolor <SRC=DST,...|file.json>]Examples:
bun src/cli.ts 1 604 1440 line v2 # all pages, line mode, V2
bun src/cli.ts 1 10 1440 page v1 no-markers # pages 1-10, page mode, no markers
bun src/cli.ts 1 604 1440 line v4 webp # V4 tajweed, WebP formatV4 tajweed colors live in the font's COLR/CPAL color tables, not in fillStyle, so they're
recolored by patching CPAL palette 0 at font-registration time. Glyph geometry (glyf/hmtx)
and alpha are left byte-identical — only color records change.
bun src/cli.ts 1 604 2160 line v4 dark # base ink → light default (#E8E0D4)
bun src/cli.ts 1 604 2160 line v4 --ink "#E8E0D4" # custom base ink (implies dark)dark/--ink <hex>— recolors the near-black base ink only; saturated tajweed rules are left as-is.--recolor "RRGGBB=RRGGBB,..."— optional, generic remap of any palette entry to a new color. Each source is matched against palette 0 with a ±10/channel tolerance. No palette is baked in — supply your own. Combine with--ink/darkto make rule colors legible on a dark background:
# Lighten the base ink and remap two tajweed rule colors in one pass:
bun src/cli.ts 1 604 2160 line v4 --ink "#E8E0D4" \
--recolor "F40000=F77B72,3F48E6=6BA6E6"
# Or supply the map as a JSON file of { "SRC": "DST" } hex pairs:
bun src/cli.ts 1 604 2160 line v4 --recolor recolor.jsondocker compose build
docker compose run generator 1 604 1440 line v2Each release ships self-contained binaries with assets embedded — no bun install, no font/layout download, no Cairo or unzip required. Only tar (in every Linux/macOS base) is used to unpack assets on first run.
Pick the variant for your platform from the latest release:
| Variant | Targets | Use when |
|---|---|---|
quran-gen-{platform} |
v1 + v2 + v4 | You want every font version in one binary |
quran-gen-v1-{platform} |
v1 only | Smaller download, single version |
quran-gen-v2-{platform} |
v2 only | Smaller download, single version |
quran-gen-v4-{platform} |
v4 only | Smaller download, single version |
Supported platforms: darwin-arm64 (Apple Silicon), linux-x64, linux-arm64.
# Apple Silicon (all versions)
curl -L https://github.com/NedaaDevs/quran-image-generator/releases/latest/download/quran-gen-darwin-arm64.tar.gz | tar xz
./quran-gen-darwin-arm64 1 604 1440 line v2
# Linux x64 (v2 only)
curl -L https://github.com/NedaaDevs/quran-image-generator/releases/latest/download/quran-gen-v2-linux-x64.tar.gz | tar xz
./quran-gen-v2-linux-x64 1 604 1440 line v2The tarball contains the binary plus a pngquant sidecar; keep them next to each other.
bun build src/cli.ts --compile --external canvas --outfile quran-gen
./quran-gen 1 604 1440 line v2By default, images include ayah end markers (ornamental numbered circles) and surah header frames rendered with the page font. Use no-markers to omit decorative elements — useful for apps that overlay their own themed markers:
- With markers — full preview with ornamental ayah markers and surah header frames baked into the image
- Without markers — text only, plus version-matched surah names (no frame). Apps can overlay custom-themed markers using glyph positions from
bounds.db
The surah frame template is exported separately to markers/surah-frame.png for apps to composite with their own styling.
output/{version}/{width}/
lines/{page}/001..015.png # per-line images (15 per page)
pages/001..604.png # full page images
markers/surah-frame.png # ornamental frame template
bounds.db # glyph bounding boxes (SQLite)
| Column | Type | Description |
|---|---|---|
| page | INTEGER | Page number (1–604) |
| line | INTEGER | Line number (1–15) |
| position | INTEGER | Word position within the line |
| surah_number | INTEGER | Surah number (1–114) |
| ayah_number | INTEGER | Ayah number within the surah |
| x | INTEGER | Left edge (px) |
| y | INTEGER | Top edge (px) |
| width | INTEGER | Glyph width (px) |
| height | INTEGER | Glyph height (px) |
| is_marker | INTEGER | 1 = ayah end marker, 0 = word |
| word_index | INTEGER | Word number within its ayah (join key: surah:ayah:word) |
| tajweed_index | TEXT | V4 tajwid rule(s): CPAL palette slot index/indices, comma-joined for multi-rule words (e.g. 15,5), joinable to tajweed_palette. NULL for V1/V2, markers, and base-ink-only words. |
The slot index is a stable rule key (it doesn't shift across font builds the way the raw RGB does); map it to a rule in your own legend. Use tajweed_palette only if you need the font's native color.
The font's canonical tajwid colors, written once (the palette is identical across all page fonts). Empty for V1/V2.
| Column | Type | Description |
|---|---|---|
| idx | INTEGER | CPAL palette slot (matches a value in tajweed_index) |
| hex | TEXT | Canonical source color #RRGGBB, uppercase |
The DB's PRAGMA user_version carries the schema version (currently 2); bump it on any schema change so clients can detect a stale download and re-fetch.
| Column | Type | Description |
|---|---|---|
| page | INTEGER | Page number (1–604) |
| line | INTEGER | Line number (1–15) |
| type | TEXT | text, surah-header, or basmala |
| surah_number | INTEGER | Surah number (nullable) |
| surah_name | TEXT | Arabic surah name (nullable) |
Apps can render marker-less images and overlay ayah markers at runtime by querying:
SELECT x, y, width, height, ayah_number
FROM glyph_bounds
WHERE page = ? AND is_marker = 1Then render each marker at the given position using the ayah number.
Assets are downloaded automatically via the interactive CLI, or manually from GitHub releases:
data/
common/fonts/ # surah name fonts, surah header font
{v1,v2,v4}/
quran-layout.db # page/line/word layout + surah metadata
fonts/p1..p604.ttf # per-page QCF fonts
| Version | Edition | Layout | Notes |
|---|---|---|---|
| V1 | 1405H Madinah Mushaf | 604 pages, 15 lines | Uthman Taha calligraphy |
| V2 | 1423H Madinah Mushaf | 604 pages, 15 lines | Updated edition |
| V4 | Tajweed | Same as V1 | Embedded colors for tajweed rules |
Special thanks to Tarteel AI for their Quranic Universal Library, which provides the essential data powering this tool:
- QCF font files — per-page V1, V2, and V4 glyph fonts
- Word-by-word glyph codes — mapping each Quranic word to its QCF codepoint
- Mushaf layout data — page/line/word mapping for the 1405H and 1423H Madinah Mushaf editions
- Surah name ligature fonts — version-matched calligraphic surah names
- quran.com-images — inspiration and original approach
- King Fahd Quran Printing Complex — the original Madinah Mushaf calligraphy by Uthman Taha
MIT