NOTE: This project is not actively maintained

Please consider using the Quran.com API instead.

quran-tajweed

Tajweed annotations for the Qur'an (riwayat hafs). The data is available as a JSON file with exact character indices for each rule, and as individual decision trees for each rule.

You can use this data to display the Qur'an with tajweed highlighting, refine models for Qur'anic speech recognition, or - if you enjoy decision trees - improve your own recitation.

The following tajweed rules are supported:

• Ghunnah (ghunnah)
• Idghaam...
  • With Ghunnah (idghaam_ghunnah)
  • Without Ghunnah (idghaam_no_ghunnah)
  • Mutajaanisain (idghaam_mutajaanisain)
  • Mutaqaaribain (idghaam_mutaqaaribain)
  • Shafawi (idghaam_shafawi)
• Ikhfa...
  • Ikhfa (ikhfa)
  • Ikhfa Shafawi (ikhfa_shafawi)
• Iqlab (iqlab)
• Madd...
  • Regular: 2 harakat (madd_2)
  • al-Aarid/al-Leen: 2, 4, 6 harakat (madd_246)
  • al-Muttasil: 4, 5 harakat (madd_muttasil)
  • al-Munfasil: 4, 5 harakat (madd_munfasil)
  • Laazim: 6 harakat (madd_6)
• Qalqalah (qalqalah)
• Hamzat al-Wasl (hamzat_wasl)
• Lam al-Shamsiyyah (lam_shamsiyyah)
• Silent (silent)

This project was built using information from ReciteQuran.com, the Dar al-Maarifah tajweed masaahif, and others.

Using the tajweed JSON file

All the data you probably need is in output/tajweed.hafs.uthmani-pause-sajdah.json. It has the following schema:

[
    {
        "surah": 1,
        "ayah": 1,
        "annotations": [
            {
                "rule": "madd_6",
                "start": 245,
                "end": 247
            },
            ...
        ]
    },
    ...
]

The start and end indices of each annotation refer to the Unicode codepoint (not byte!) offset within the Tanzil.net Uthmani Qur'an text. NOTE: that the encoding of the files available from Tanzil.net has changed slightly since the annotations were generated, so please use this copy of the Qur'an text file: quran-uthmani.txt (downloaded ca. Apr 6, 2017). If you use a different Qur'an text file, you must rebuild the data file from scratch (at your own risk) - refer to the next section.

This data file is licensed under a Creative Commons Attribution 4.0 International License, while the original Tanzil.net text file linked above is made available under the Tanzil.net terms of use.

Using the decision trees

tajweed_classifier.py is a script that takes Tanzil.net "Text (with aya numbers)"-style input via STDIN, and produces the tajweed JSON file (as described above) via STDOUT. It reads the decision trees from rule_trees/*.json. Note that the trees have been built to function best with the Madani text; they rely on the prescence of pronunciation markers (e.g. maddah) that may not be present in other texts.

Ruleset reference

The following are renderings of the decision trees used to determine where each tajweed annotation starts and stops. Attributes are grouped by the letters they belong to, a letter being defined as a base character (e.g. ل) plus any diacritics that follow (codepoints in the Mn category). Superscript/dagger alif is counted as a base character. The numbers prefixing each attribute indicate which letter the attribute belongs to: negative referring to previous letters, positive to future letters. Attributes starting with 0_... refer to the exact character being considered. Annotations do not always start or stop on letter boundaries. Refer to tajweed_classifier.py for the definition of each attribute.

ghunnah

Start	End

hamzat_wasl

Start	End

idghaam_ghunnah

Start	End

idghaam_mutajanisayn

Start	End

idghaam_mutaqaribayn

Start	End

idghaam_no_ghunnah

Start	End

idghaam_shafawi

Start	End

ikhfa

Start	End

ikhfa_shafawi

Start	End

iqlab

Start	End

lam_shamsiyyah

Start	End

madd_2

Start	End

madd_246

Start	End

madd_6

Start	End

madd_munfasil

Start	End

madd_muttasil

Start	End

qalqalah

Start	End

silent

Start	End