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]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 formatdocker compose build
docker compose run generator 1 604 1440 line v2bun build src/cli.ts --compile --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 |
| 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