Contextual Letter Forms
Each Arabic letter has up to 4 forms (initial, medial, final, isolated) depending on position. Generic renderers often pick the wrong form, breaking the cursive flow.
Puppeteer, wkhtmltoimage, and Cloudinary weren't built for Arabic. Broken diacritics, wrong ligatures, and mangled RTL layout are the norm — not the exception.
Feature Comparison
An honest comparison of Arabic text rendering capabilities.
| Feature | Mirqam | Puppeteer / wkhtmltoimage | Cloudinary |
|---|---|---|---|
| RTL layout support | Native — built for RTL | Depends on OS/fonts | Partial — often broken |
| Diacritics (tashkeel) | Pixel-perfect positioning | Often mispositioned | Frequently broken |
| OpenType shaping | Full (ligatures, kashida, contextual forms) | Depends on OS libraries | Limited |
| Custom fonts (TTF/OTF) | Upload and use instantly | Install on server manually | Paid feature, limited shaping |
| Deterministic output | Identical across all environments | Varies by OS and browser version | Generally consistent |
| Speed (per image) | Milliseconds — no browser overhead | Seconds — headless Chromium startup | Sub-second — cloud processing |
| API simplicity | Single REST call with JSON body | Custom code + HTML template | URL-based transforms, complex for text |
The Technical Problem
Arabic isn't just "right-to-left English." It requires a completely different text shaping pipeline.
Each Arabic letter has up to 4 forms (initial, medial, final, isolated) depending on position. Generic renderers often pick the wrong form, breaking the cursive flow.
Harakat (fatha, damma, kasra, shadda) must be positioned precisely above or below letters using OpenType GPOS tables. Without proper mark positioning, diacritics float in the wrong place.
Arabic fonts contain mandatory ligatures (like lam-alef) and optional ones for aesthetic quality. Kashida (elongation) is used for justified text. Both require OpenType GSUB support.
Mixing Arabic with English or numbers requires the Unicode Bidirectional Algorithm. Incorrect BiDi handling causes text to appear in the wrong order — a common issue with image-generation APIs.
Server environments typically lack Arabic fonts. Without proper fallback chains, you get tofu (missing glyph boxes) or substitution with a system font that doesn't match your design.
Puppeteer output varies between macOS, Linux, and Docker containers because each uses different text shaping libraries. Mirqam produces identical output everywhere.
FAQ
Puppeteer relies on the underlying OS text shaping engine and installed fonts. Most server environments lack proper Arabic fonts and OpenType shaping support, causing diacritics (tashkeel) to appear disconnected or mispositioned.
Cloudinary supports basic text overlays, but its rendering engine does not handle Arabic ligatures, kashida, or diacritics positioning correctly. Characters may appear disjoined or in the wrong order.
Arabic is a cursive script where letters change shape based on position (initial, medial, final, isolated). Add diacritics (harakat), kashida (elongation), and RTL layout, and you need a full OpenType shaping engine — not just font rendering.
Yes. Upload any TTF or OTF font file directly. Mirqam's rendering engine applies full OpenType shaping including ligatures, contextual alternates, and mark positioning — ensuring your custom font displays exactly as the type designer intended.
Mirqam generates images in milliseconds without spinning up a headless browser. Puppeteer-based solutions require launching Chromium, loading a page, and taking a screenshot — typically 2-10x slower and far more resource-intensive.
One API call. Perfect Arabic every time. Sign up and get 100 free credits to test with your own fonts and templates.