هندسة مزامنة الآيات
رواية ورش مقابل رواية حفص Verse Synchronization Architecture
Warsh Narration vs. Hafs Narration

1 Background and Problem

Why is this rare online?

The difference in verse count between Warsh and Hafs is documented in Quranic sciences literature, but there is no digital resource — within our research — that documents transition points verse-by-verse in a programmable format. Most sources only mention that "the Kufi count differs from the Madani count" without specifying the exact surah and verse.

Technical Context

The app displays the Warsh Mushaf and supports audio playback and commentary display. The commentary source is an external API that uses Hafs numbering (Kufi count). When tapping a verse in Warsh mode, the function was sending the verse number as-is to the API, returning data for a different verse in surahs where the numbering diverges.

2 Core Concepts

2.1 Types of Divergence

Merge — Warsh combines what Hafs separates:

H[n] + H[n+1]  →  W[k]        (Warsh has fewer verses)

Split — Warsh divides what Hafs keeps as one:

H[n]  →  W[k] + W[k+1]        (Warsh has more verses)

Opening Letters (Fawatih) Merge: Letters like "Alif Lam Meem" and "Ha Meem" are counted in Warsh as one verse with the following text, while Hafs counts them independently. This is the most frequent type, appearing in 16 surahs.

2.2 The Offset

The offset is the difference between a Warsh verse number and its Hafs counterpart:

W[n]  =  H[n + offset]

• offset = 0: Direct match
• offset = +1: Warsh had a prior merge (Hafs is ahead by one)
• offset = -1: Warsh had a prior split (Hafs is behind by one)

The offset changes at every merge or split point and stays constant until the next one.

3 Technical Solution

3.1 Code Structure

// src/utils/tafsir.ts

const WARSH_EXCEPTIONS: Record<number, ExceptionType> = { ... }

export function warshToHafsAyahs(sura: number, warshAya: number): number[]

The function returns an array (not a single number) because a single Warsh verse can correspond to two Hafs verses when merged.

3.2 Exception Types

type ExceptionType =
  | { type: "manual"; map: Record<number, number[]> }
  | { type: "offset"; mergeAtWarshAyah: number; hafsTargetsToMerge: number[]; offsetForSubsequent: number }
  | { type: "advanced"; explicit_map: Record<number, number[]>; ranges: Range[] }

3.3 Advanced Example — Surah Maryam

// Maryam (19): W=99, H=98 — opening merge + two internal splits
19: {
  type: "advanced",
  explicit_map: {
    1: [1, 2],   // W1 = H1+H2  (Kaf Ha Ya Ain Sad merge)
    40: [41],    // W40 = H41   (first half of split 1)
    41: [41],    // W41 = H41   (second half of split 1)
    75: [75],    // W75 = H75   (first half of split 2)
    76: [75],    // W76 = H75   (second half of split 2)
  },
  ranges: [
    { warshStart: 2,  warshEnd: 39, hafsOffset:  1 },
    { warshStart: 42, warshEnd: 74, hafsOffset:  0 },
    { warshStart: 77, warshEnd: 99, hafsOffset: -1 },
  ],
}

4 Complete Surah Tables

Category 0 — Manual map

Category 1 — Simple opening merge (fixed offset +1)

Category 1b — Opening merge + internal split (net = 0)

Category 2 — Multiple opening merges

Category 3 — Single split or merge (diff=±1)

Category 4 — Single internal merge (diff=+1)

Category 4b — Single internal split (diff=-1)

Category 5 — Multiple structural shifts

5 Verification Methodology

5.1 Last-Verse Validation

The most reliable test: verifying that warshToHafsAyahs(W_last) == H_last for every surah:

mapped = warsh_to_hafs(exc, w_last)
assert mapped[-1] == h_last  # must match

Passed for all 56 surahs in WARSH_EXCEPTIONS.

5.2 Content Validation

Comparing actual verse text at transition points using Arabic normalization:

def normalize(text):
    text = re.sub(r'[أإآٱ]', 'ا', text)
    text = text.replace('ى','ي').replace('ے','ي')
    text = re.sub(r'[^\u0621-\u064A\s]', '', text)  # Arabic letters only

6 Technical Corrections & Revisions

All of the following were discovered through actual text content inspection or through last-aya test failures:

6.1 Revisions During Initial Map Construction

6.2 Revisions During Full Verification Pass

7 Final Statistics

8 Developer Notes

Uthmanic Script Differences — Normal & Expected

When comparing Warsh and Hafs text programmatically, the following script differences are intentional and documented. Do not treat them as transcription issues:

Audio Logic

The function warshToHafsAyahs() is used in two modes:

1. Commentary: Always — the commentary source uses Hafs numbering
2. Audio (CDN): Only when moqriId.startsWith("warsh_") — CDN audio files are numbered with Hafs numbering even for Warsh reciters
3. Audio (DB): Not needed — local DB reciters are already numbered with Warsh numbering

9 Sources

• Database: Warsh text with Madani numbering (Last Madani Count)
• Hafs text: Hafs text with Kufi numbering
• Commentary source: External API using Hafs/Kufi numbering
• Academic reference: Quranic sciences — works on verse counting and tables comparing the Madani and Kufi counts