A high-performance media generation library for rendering Quranic Arabic text and translations into customizable, professional-grade images.

Requirements: Python 3.13+

📌 Table of Contents

• User Guide
  • Installation
  • Quick Start
  • Presets Reference
  • Built-in Workflows
  • Demo Gallery
• Developer Guide
  • Architecture
  • Core Thesis
  • Core API Reference
  • Advanced Workflows
  • Performance & Parallelism
  • Development Suite
• Community & License

User Guide

Installation

# Install from PyPI (recommended)
pip install quranmedialib

# Or clone and install from source
git clone https://github.com/AtTheZenith/quranmedialib.git
cd quranmedialib

# Install with uv (recommended)
uv pip install -e .

Quick Start

from quranmedialib import DatabaseManager, VerseWorkflow, LANDSCAPE_PRESET

# Initialize database manager
db = DatabaseManager()

# Load a 1080p Landscape preset
preset = LANDSCAPE_PRESET["default"]["1080p"]
workflow = VerseWorkflow(preset)

# Render Surah 1, Ayah 1
translations = ["In the name of Allah,", "the Entirely Merciful, the Especially Merciful."]
pages = list(workflow.get_iterator(surah=1, ayah=1, translations=translations))

# Save first page
pages[0][0].save("output.png")

db.close()

Presets Reference

The library uses a resolution-independent system. All sizing parameters scale linearly from a 1080p baseline.

Built-in Workflows

Workflows are high-level orchestrators that handle data retrieval, layout, and rendering.

SurahWorkflow

Processes an entire surah page by page.

from quranmedialib import SurahWorkflow, LANDSCAPE_PRESET

preset = LANDSCAPE_PRESET["default"]["1080p"]
workflow = SurahWorkflow(preset)

for page_num, page_images in enumerate(workflow.get_iterator(surah=112), 1):
    for img in page_images:
        img.save(f"surah112_p{page_num}.png")

VerseRangeWorkflow

Processes a range of verses with support for parallel rendering.

from quranmedialib import VerseRangeWorkflow, SQUARE_PRESET

preset = SQUARE_PRESET["default"]["1080p"]
workflow = VerseRangeWorkflow(preset)

# translations: list[list[str]] -> [verse_index][page_index]
translations = [["Trans V1"], ["Trans V2"]] 
iterator = workflow.get_iterator(surah=1, start_ayah=1, end_ayah=2, translations=translations)

Demo Gallery

Visual examples of generated content:

Preset	Image
Landscape (1080p)
Story (1080p)
Square (1080p)

Developer Guide

Architecture

graph TD
    DB[(SQLite Database)] -->     WF[Workflow Orchestrator]
    WF --> Layout[Layout Engine: VImage]
    Layout --> Pipe[Rendering Pipeline]
    Pipe --> Mask[Mask-First Rendering]
    Mask --> Comp[Composition: Frame]
    Comp --> Out[Final Image]
    
    subgraph Config
        FC[FrameConfig] -.-> Comp
        VC[VerseConfig] -.-> Layout
        WC[WordConfig] -.-> Pipe
        TC[TextConfig] -.-> Pipe
    end

Core Thesis

QuranMediaLib is built on the "Boring Code" philosophy: prioritizing linear, obvious logic over clever abstractions to ensure long-term maintainability.

Key Engineering Pillars:

• Resolution Independence: Layouts are defined relative to a 1080p height and scaled linearly.
• Memory Efficiency: Use of __slots__ for high-frequency objects and lru_cache for database queries.
• Performance: Mask-first rendering minimizes expensive RGBA operations.

Core API Reference

DatabaseManager

A thread-safe singleton managing SQLite connections to Quranic databases.

• get_verse(surah, ayah): Retrieves verse text.
• get_verses_from_surah(surah): Retrieves all verses in a surah.
• minimize_caches(): Explicitly clears internal LRU caches.

Configuration

• Preset: Unified config container (preset.frame, preset.word, preset.verse, preset.text).
• FrameConfig: Controls frame dimensions, background, and alignment.
• VerseConfig: Controls word spacing, row spacing, max rows, and wrapping.
• WordConfig: Defines Arabic font, size, colors, and spacing.
• TextConfig: Defines translation font, size, and rich-text formatting.

Resource Management

Custom assets can be loaded via:

• FontResource.from_path("path/to/font.ttf")
• DatabaseConfig.from_path("path/to/db.sqlite")

Rich Text Formatting

Translation text supports rich styling through inline tags.

Syntax:: #<style>#<color>#text# — the closing # is mandatory.

Examples:

"#b#ff0000ff#Bold red text#"
"#i#00ff00#Italic green text#"
"#bi#0000ffff#Bold italic blue text#"

A # that does not form a valid tag (e.g. a missing color or a stray hash) is rendered literally and logs a WARNING that points out the malformed tag and the expected syntax. Suppress that warning with TextConfig(ignore_non_token_hashtags=True), which still parses valid tags while leaving the rest as literal text.

See the API reference for the full TextConfig surface.

Advanced Workflows

IsolateWordsWorkflow

Used to isolate individual words within their layout context, useful for word-by-word study tools.

from quranmedialib import IsolateWordsWorkflow, LANDSCAPE_PRESET

preset = LANDSCAPE_PRESET["default"]["1080p"]
workflow = IsolateWordsWorkflow(preset)

# Isolates each word of the verse
iterator = workflow.get_iterator(
    surah=1, 
    verse_words=["الله", "الرحمن", "الرحيم"], 
    translations=["Allah", "The Merciful", "The Compassionate"]
)

Performance & Parallelism

For bulk rendering, the library provides ParallelRenderer, which distributes tasks across CPU cores.

• Execution Modes: ExecutionMode.PROCESS (recommended for CPU-heavy tasks) or ExecutionMode.THREAD.
• Memory Guard: Per-process RSS enforcement via worker_heartbeat() every 10 verses. Workers crash immediately if they exceed 256MB. Aggregate RSS ~700MB during parallel renders is safe — no aggregate monitor needed.

Development Suite

quranmedialib.check — Validation, Benchmarking & Reference Management

The check module is the canonical entrypoint for all regression testing. It wraps pixel validation, performance benchmarks, and unit tests into a single command.

# Install dev dependencies (uv sync installs the dev group: ruff, pytest, psutil)
uv sync

# Full suite (pixel validation + benchmarks + unit tests)
uv run -m quranmedialib.check test

# Quick pixel validation only (no benchmarks)
uv run -m quranmedialib.check test --no-benchmark

# Unit tests only (skip pixel validation and benchmarks)
uv run -m quranmedialib.check test --unit

# (Re)generate reference images for v4.1.0
uv run -m quranmedialib.check update --version v4.1.0

# Cross-version pixel comparison
uv run -m quranmedialib.check compare v4.0.0 v4.1.0

# Standalone benchmark run
uv run -m quranmedialib.check benchmark

# List all canonical validation scenarios
uv run -m quranmedialib.check list

Reference pipeline: The update command renders all canonical scenarios to PNG files under src/quranmedialib/check/references/<version>/. Each reference set includes scenarios.json (metadata), sha256sums (integrity hashes), and a perf.json benchmark artifact. The compare command performs pixel-level diffs between versions.

Performance benchmarks: The benchmark path runs file-based rendering (saves PNGs to disk via parallel async I/O, counts pages) to avoid deserializing ~3.8GB of RGBA image bytes over IPC. Memory is checked every 10 verses via worker_heartbeat() (per-process 256MB limit). Batch sizes use natural chunking (ceil(tasks / workers)) with adaptive down-capping in bytes IPC mode via _bytes_mode_max_batch(). No aggregate memory monitor — per-process enforcement catches leaks before they cascade.

Lint and Format

uv run -m ruff check .
uv run -m ruff format .

Community & License

We welcome contributions from developers who value engineering rigor and performance.

• Contribute: See CONTRIBUTING.md for technical standards.
• Conduct: See CODE_OF_CONDUCT.md.
• License: Apache License 2.0 - see LICENSE.