Quran Transcript

بفضل الله وحده عز وجل نقدم الرسم الصوتي للقرآن الكريم الملم بجل قواعد التجويد وصفات الحوف

`quran-transcript` package

🆕 ما الجديد في الإصدار 0.5.1 (What's New in Version 0.5.1)

🎯 تحليل أخطاء التلاوة (Recitation Error Analysis)

إضافة دالة explain_error لمقارنة النص الصوتي المتوقع (المرجع) مع النص الصوتي المُتنبأ به (مثلاً من قارئ أو نموذج تعلم آلي).
توفير تحليل تفصيلي للأخطاء يشمل:
- نوع الخطأ: تجويدي (tajweed)، عادي (normal)، أو حركات (tashkeel).
- نوع الخطأ الكلامي: إدراج (insert)، حذف (delete)، أو استبدال (replace).
- قواعد التجويد المرتبطة بالخطأ (مثل المد، القلقلة، الغنة) مع تحديد الطول المتوقع والفعلي عند الاقتضاء.
تمثيل النتائج باستخدام كائن ReciterError الذي يحتوي على معلومات دقيقة عن موقع الخطأ في النص العثماني والصوتي.
هذه الأداة مفيدة لتقييم أداء قراء القرآن، وتحليل أخطاء نماذج التعرف على الكلام، وتقديم تغذية راجعة للمتعلمين.

🆕 ما الجديد في الإصدار 0.4.0 (What's New in Version 0.4.0)

🔍 بحث صوتي ضبابي محسّن (Optimized Fuzzy Phonetic Search)

إضافة فئة PhoneticSearch للبحث عن نصوص صوتية في القرآن باستخدام التشابه الضبابي (Levenshtein distance) باستخدام مكتبة fuzzysearch
بناء فهرس مسبق للرسم الصوتي (phoneme index) لتسريع البحث بشكل كبير.
دعم تحديد نسبة الخطأ المسموح بها (error_ratio) للحصول على نتائج حتى مع الاختلافات الطفيفة.
تمثيل النتائج باستخدام PhonemesSearchSpan و PhonmesSearhResult مع معلومات دقيقة عن الموقع (السورة، الآية، الكلمة، الحرف، المؤشر الصوتي).

🛠️ بناء الفهرس (Building the Index)

يتم تضمين الفهرس الجاهز (ph_index.npy و ref_norm_ph.txt) داخل الحزمة، ولا يحتاج المستخدم العادي إلى بنائه.
للمطورين الذين يرغبون في إعادة بناء الفهرس (بعد تعديل قواعد التحويل الصوتي مثلاً)، يمكن استخدام الأمر:
```
python -m ph-ndx
```
وسيتم حفظ الملفات في مجلد quran-script داخل الحزمة.

🆕 ما الجديد في الإصدار 0.3.0 (What's New in Version 0.3.0)

📍 خرائط المواقع الجديدة (New Position Mappings)

أسرع مرتان في عملية إنشاء الرسم الصوتي (Faster 2x in phonetizatoin)
تمثيل الحروف المحذوفة ب MappingPos(pos=(x, x), deleted=True - حيث x رقم صحيح أكبر من الصفر - بدلا من None (Represent deleted characther with MappingPos(pos=(x, x), deleted=True) -where x is an integer >=0- instead of None)

🆕 ما الجديد في الإصدار 0.2.0 (What's New in Version 0.2.0)

📍 خرائط المواقع الجديدة (New Position Mappings)

إضافة خرائط المواقع من الرسم العثماني إلى الرسم الصوتي (Added position mappings from Uthmani script to phonetic script)
تتبع دقيق لتحويل كل حرف إلى موضعه الجديد (Precise tracking of character transformations)
دعم تمثيل الأحرف المحذوفة بقيمة None (Support for deleted characters representation with None)

📖 Quran Transcript

🔧 Installation

Install the package directly from GitHub using pip:

pip install quran-transcript

🧠 Usage Examples

🕋 Aya Object

إنشاء كائن Aya لتمثيل آية محددة واسترجاع معلوماتها

from quran_transcript import Aya

aya = Aya(1, 1)  # سورة الفاتحة، الآية 1
print(aya)

aya_info = aya.get()
print(aya_info)

🔁 Loop Through All Surahs

التنقل عبر جميع الآيات في القرآن

start_aya = Aya()
for aya in start_aya.get_ayat_after():
    aya_info = aya.get()
    # Do something with the aya info

🧮 Get Number of Verses per Surah

بناء خريطة بأرقام السور وعدد آياتها

sura_to_aya_count = {}
start_aya = Aya(1, 1)

for i in range(1, 115):  # 114 سورة في القرآن
    aya.set(i, 1)
    sura_to_aya_count[i] = aya.get().num_ayat_in_sura

print(sura_to_aya_count)

🔄 Convert Imlaey Script to Uthmani

تحويل الرسم الإملائي للرسم العثماني

from quran_transcript import search, Aya

imlaey_text = 'فأخرج به من الثمرات رزقا لكم'
results = search(
    imlaey_text,
    start_aya=Aya(2, 13),
    window=20,
    remove_tashkeel=True
)

uthmani_script = results[0].uthmani_script
print(uthmani_script)

🔤 Convert Uthmani Script to Phonetic Script

تحويل الرسم العثماني للرسم الصوتي للقرآن

from quran_transcript import Aya, search, quran_phonetizer, MoshafAttributes
import json

imlaey_text = "بسم الله الرحمن الرحيم"
results = search(
    imlaey_text,
    start_aya=Aya(1, 1),
    window=2,
    remove_tashkeel=True
)

# الحصول على الرسم العثماني
uthmani_script = results[0].uthmani_script
print(f"الرسم العثماني:\n{uthmani_script}")

# إعداد خصائص المصحف للتحويل الصوتي
moshaf = MoshafAttributes(
    rewaya="hafs",
    madd_monfasel_len=4,
    madd_mottasel_len=4,
    madd_mottasel_waqf=4,
    madd_aared_len=4,
)

# الحصول على الرسم الصوتي مع الخرائط
phonetic_script = quran_phonetizer(uthmani_script, moshaf)

print('\n' * 2)
print(f"الرسم الصوتي:\n{phonetic_script.phonemes}")
# print(f"صفات الحروف:\n{phonetic_script.sifat}")
print('\n' * 2)
print("صفات الحروف:")
for sifa in phonetic_script.sifat:
    print(json.dumps(sifa.model_dump(), ensure_ascii=False, indent=4))
    print()


# جديد: عرض خرائط المواقع
print('\n' * 2)
print("خرائط المواقع:")
for idx, (uth_char, mapping) in enumerate(zip(uthmani_script, phonetic_script.mappings)):
    if not mapping.deleted:
        # استخراج الصوت لهذا الحرف
        phoneme = phonetic_script.phonemes[mapping.pos[0]:mapping.pos[1]]
        print(f"حرف: '{uth_char}' -> صوت: '{phoneme}' (موقع: {mapping.pos})")
    else:
        print(f"حرف: '{uth_char}' -> محذوف")

📘 For more information on MoshafAttributes, refer to the Quran Dataset Documentation.

الرسم الصوتي للقرآن الكريم

📊 خرائط المواقع (Position Mappings)

خرائط المواقع توفر تتبع دقيق لمواقع الأحرف من النص العثماني الأصلي إلى النص الصوتي المحول. Position mappings provide precise tracking of character positions from original Uthmani text to converted phonetic text.

# i الوصول إلى بيانات الخرائط
mappings = phonetic_script.mappings  # List[MappingPos | None]
phonemes = phonetic_script.phonemes  # str

# المرور على خرائط الأحرف
for idx, mapping in enumerate(mappings):
    if mapping is not None:
        # الحصول على امتداد الموقع
        start, end = mapping.pos  # Python-style slice notation
        # استخراج الصوت المقابل
        char_phoneme = phonemes[start:end]
        print(f"الحرف {idx} ينتقل إلى الصوت في الموقع ({start}, {end})")
    else:
        print(f"الحرف {idx} تم حذفه أثناء التحويل")

فهم MappingPos (Understanding MappingPos)

@dataclass
class MappingPos:
    """خرائط المواقع لتحويلات الأحرف (Position mapping for character transformations)"""
    pos: tuple[int, int]  # (بداية، نهاية) - بالطريقة البايثونية
    tajweed_rules: list[TajweedRule] | None = None  # قواعد التجويد المرتبطة
    deleted: bool = False  # حالة الحذف - True إذا تم حذف الحرف مع حفظ الموقع وتتساوي البداية والنهاية في ال `pos`

📖 مثال على استخدام البحث الصوتي (Example of Phonetic Search)

from quran_transcript import PhoneticSearch

# إنشاء كائن البحث (سيحمل الفهرس تلقائياً)
searcher = PhoneticSearch()

# نص صوتي للبحث (يمكن أن يكون غير دقيق)
query = "قَلِۦۦلَممممَاا"  # مثال من الاختبارات

# البحث بنسبة خطأ 10%
results = searcher.search(query, error_ratio=0.1)

# عرض النتائج
for r in results:
    print(f"سورة {r.start.sura_idx}, آية {r.start.aya_idx}")
    print(f"  من كلمة {r.start.uthmani_word_idx} حرف {r.start.uthmani_char_idx} إلى كلمة {r.end.uthmani_word_idx} حرف {r.end.uthmani_char_idx}")
    print(f"  المؤشرات الصوتية: {r.start.phonemes_idx} - {r.end.phonemes_idx}")

# استخراج النص العثماني المطابق
uthmani_text = searcher.get_uthmani_from_result(results[0])
print(f"النص العثماني: {uthmani_text}")

📦 كائنات النتائج (Result Dataclasses)

`PhonemesSearchSpan`

يمثل موقعاً واحداً في القرآن (بداية أو نهاية المطابقة):

sura_idx: رقم السورة (1-based)
aya_idx: رقم الآية (1-based)
uthmani_word_idx: فهرس الكلمة داخل الآية (0-based)
uthmani_char_idx: فهرس الحرف داخل الكلمة (0-based، شامل للبداية، غير شامل للنهاية)
phonemes_idx: فهرس المجموعة الصوتية في التسلسل الصوتي المرجعي (0-based)

`PhonmesSearhResult`

يحتوي على زوج من PhonemesSearchSpan للبداية والنهاية:

start: موقع بداية المطابقة
end: موقع نهاية المطابقة (غير شامل)

📖 مثال على تحليل أخطاء التلاوة (Error Analysis Example)

from quran_transcript import (
    quran_phonetizer,
    MoshafAttributes,
    ReciterError,
    explain_error,
)

# إعداد خصائص المصحف
moshaf = MoshafAttributes(
    rewaya="hafs",
    madd_monfasel_len=4,
    madd_mottasel_len=4,
    madd_mottasel_waqf=4,
    madd_aared_len=4,
)

# النص العثماني الأصلي
uthmani_text = "قَالُوٓا۟"

# نص صوتي متوقع (مرجعي)
ref_out = quran_phonetizer(uthmani_text, moshaf)
print("المرجع:", ref_out.phonemes)

# نص صوتي مُتنبأ به (به أخطاء)
predicted_text = "فكۥۥلۥۥ"
print("المتنبأ به:", predicted_text)

# تحليل الأخطاء
errors = explain_error(
    uthmani_text=uthmani_text,
    ref_ph_text=ref_out.phonemes,
    predicted_ph_text=predicted_text,
    mappings=ref_out.mappings,
)

# عرض النتائج
for err in errors:
    print("\n" + "="*50)
    print(f"الموقع في العثماني: `{uthmani_text[err.uthmani_pos[0]:err.uthmani_pos[1]]}`, {err.uthmani_pos}")
    print(f"الموقع في الصوتي: `{ref_out.phonemes[err.ph_pos[0]:err.ph_pos[1]]}`, {err.ph_pos}")
    print(f"نوع الخطأ: {err.error_type} - {err.speech_error_type}")
    print(f"المتوقع: '{err.expected_ph}' - المُتنبأ به: '{err.preditected_ph}'")
    if err.ref_tajweed_rules:
        for rule in err.ref_tajweed_rules:
            print(f"  قاعدة تجويد مرجعية: {rule.name.ar} ({rule.name.en})")
    if err.replaced_tajweed_rules:
        for rule in err.replaced_tajweed_rules:
            print(f"  قاعدة تجويد مستبدلة: {rule.name.ar} ({rule.name.en})")
    if err.missing_tajweed_rules:
        for rule in err.missing_tajweed_rules:
            print(f"  قاعدة تجويد مفقودة: {rule.name.ar} ({rule.name.en})")

مخرجات متوقعة (Partial output):

المرجع: قَاالُۥۥ
المتنبأ به: فكۥۥلۥۥ

==================================================
الموقع في العثماني: ``, (0, 0)
الموقع في الصوتي: ``, (0, 0)
نوع الخطأ: normal - insert
المتوقع: '' - المُتنبأ به: 'ف'

==================================================
الموقع في العثماني: `قَ`, (0, 2)
الموقع في الصوتي: `قَ`, (0, 2)
نوع الخطأ: normal - replace
المتوقع: 'قَ' - المُتنبأ به: 'ك'

==================================================
الموقع في العثماني: `ا`, (2, 3)
الموقع في الصوتي: `اا`, (2, 4)
نوع الخطأ: tajweed - replace
المتوقع: 'اا' - المُتنبأ به: 'ۥۥ'
  قاعدة تجويد مرجعية: المد الطبيعي (Normal Madd)
  قاعدة تجويد مستبدلة: المد الطبيعي (Normal Madd)

==================================================
الموقع في العثماني: `لُ`, (3, 5)
الموقع في الصوتي: `لُ`, (4, 6)
نوع الخطأ: tashkeel - delete
المتوقع: 'لُ' - المُتنبأ به: 'ل'

📦 كائنات تحليل الأخطاء (Error Analysis Dataclasses)

`ReciterError`

يمثل خطأ واحد في التلاوة:

uthmani_pos: tuple[int, int] – موقع الخطأ في النص العثماني (بداية، نهاية).
ph_pos: tuple[int, int] – موقع الخطأ في النص الصوتي المرجعي (بداية، نهاية).
error_type: Literal["tajweed", "normal", "tashkeel"] – نوع الخطأ.
speech_error_type: Literal["insert", "delete", "replace"] – نوع الخطأ الكلامي.
expected_ph: str – المقطع الصوتي المتوقع.
preditected_ph: str – المقطع الصوتي المُتنبأ به.
expected_len: Optional[int] – الطول المتوقع (لأخطاء المد مثلاً).
predicted_len: Optional[int] – الطول الفعلي.
ref_tajweed_rules: Optional[list[TajweedRule]] – قواعد التجويد المرتبطة بالمقطع المتوقع.
inserted_tajweed_rules, replaced_tajweed_rules, missing_tajweed_rules: Optional[list[TajweedRule]] – قواعد التجويد التي تم إدراجها أو استبدالها أو فقدانها.

الحروف: (43)

Phoneme Name	Symbol	الحرف بالعربية
hamza	ء	همزة
baa	ب	باء
taa	ت	تاء
thaa	ث	ثاء
jeem	ج	جيم
haa_mohmala	ح	حاء
khaa	خ	خاء
daal	د	دال
thaal	ذ	ذال
raa	ر	راء
zay	ز	زاي
seen	س	سين
sheen	ش	شين
saad	ص	صاد
daad	ض	ضاد
taa_mofakhama	ط	طاء
zaa_mofakhama	ظ	ظاء
ayn	ع	عين
ghyn	غ	غين
faa	ف	فاء
qaf	ق	قاف
kaf	ك	كاف
lam	ل	لام
meem	م	ميم
noon	ن	نون
haa	ه	هاء
waw	و	واو
yaa	ي	ياء
alif	ا	نصف مد ألف
yaa_madd	ۦ	نصف مد ياء
waw_madd	ۥ	نصف مد واوا
fatha	َ	فتحة
dama	ُ	ضمة
kasra	ِ	كسرة
fatha_momala	۪	فتحة ممالة
alif_momala	ـ	ألف ممالة
hamza_mosahala	ٲ	همزة مسهلة
qlqla	ڇ	قلقة
noon_mokhfah	ں	نون مخفاة
meem_mokhfah	۾	ميم مخفاة
sakt	ۜ	سكت
dama_mokhtalasa	ؙ	ضمة مختلسة (عند الروم في تأمنا)

صفات الحروف (10)

Sifat (English)	Sifat (Arabic)	Available Attributes (English)	Available Attributes (Arabic)
hams_or_jahr	الهمس أو الجهر	hams, jahr	همس, جهر
shidda_or_rakhawa	الشدة أو الرخاوة	shadeed, between, rikhw	شديد, بين بين, رخو
tafkheem_or_taqeeq	التفخيم أو الترقيق	mofakham, moraqaq, low_mofakham	مفخم, مرقق, أدنى المفخم
itbaq	الإطباق	monfateh, motbaq	منفتح, مطبق
safeer	الصفير	safeer, no_safeer	صفير, لا صفير
qalqla	القلقلة	moqalqal, not_moqalqal	مقلقل, غير مقلقل
tikraar	التكرار	mokarar, not_mokarar	مكرر, غير مكرر
tafashie	التفشي	motafashie, not_motafashie	متفشي, غير متفشي
istitala	الاستطالة	mostateel, not_mostateel	مستطيل, غير مستطيل
ghonna	الغنة	maghnoon, not_maghnoon	مغنون, غير مغنون

Needs refactory

Build for Source

create a venv or a conda environment to avoid coflicts, Then

cd quran-transcript
python -m pip install -r ./

Annotation Application of annotation imlaey to uthmnai

To start server:

python -m uvicorn server:app --port 900

To start streamlit

python -m streamlit run streamlit_app

Quran Script Description

[TODO]

`merge_uthmani_imlaey.py`

Merging Uthmani Quran and Imlaye Quran scipts of tanzil into a single scipt (".xml" and ".json")

Uthmanic: without (pause marks, sajda signs, hizb signs)
Imlaey: without (pause marks, sajda signs, hizb signs and tatweel sign) Usage:

usage: Merge Uthmani and Imlaey Script into a single scipt [-h] [--uthmani-file UTHMANI_FILE] [--imlaey-file IMLAEY_FILE] [--output-file OUTPUT_FILE]

options:
  -h, --help            show this help message and exit
  --uthmani-file UTHMANI_FILE
                        The path to the input file "file.xml"
  --imlaey-file IMLAEY_FILE
                        The path to the input file "file.xml"
  --output-file OUTPUT_FILE
                        The path to the output file either ".json" or ".xml"

Example within the repo (json):

python merge_uthman_imlaey.py --uthmani-file quran-script/quran-uthmani-without-pause-sajda-hizb-marks.xml --imlaey-file quran-script/quran-simple-imlaey-without-puase-sajda-hizb-marks-and-tatweel.xml --output-file quran-script/quran-uthmani-imlaey.json

Example within the repo (json):

python merge_uthman_imlaey.py --uthmani-file quran-script/quran-uthmani-without-pause-sajda-hizb-marks.xml --imlaey-file quran-script/quran-simple-imlaey-without-puase-sajda-hizb-marks-and-tatweel.xml --output-file quran-script/quran-uthmani-imlaey.xml

TODO

quran_transcript docs
adding tests
CI/CD with github

Name		Name	Last commit message	Last commit date
Latest commit History 281 Commits
.github/workflows		.github/workflows
app		app
quran-script		quran-script
src/quran_transcript		src/quran_transcript
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
merge_uthmani_imaley.py		merge_uthmani_imaley.py
parse_quranic_corpus.py		parse_quranic_corpus.py
process_quran_alphabet.py		process_quran_alphabet.py
process_uthmani_alphabet.py		process_uthmani_alphabet.py
pyproject.toml		pyproject.toml
quran_script_map_stats.py		quran_script_map_stats.py
requirements.txt		requirements.txt
server.py		server.py
streamlit_app.py		streamlit_app.py
style.css		style.css
uv.lock		uv.lock
visualise_letters.py		visualise_letters.py

Folders and files

Latest commit

History

Repository files navigation

Quran Transcript

quran-transcript package

🆕 ما الجديد في الإصدار 0.5.1 (What's New in Version 0.5.1)

🎯 تحليل أخطاء التلاوة (Recitation Error Analysis)

🆕 ما الجديد في الإصدار 0.4.0 (What's New in Version 0.4.0)

🔍 بحث صوتي ضبابي محسّن (Optimized Fuzzy Phonetic Search)

🛠️ بناء الفهرس (Building the Index)

🆕 ما الجديد في الإصدار 0.3.0 (What's New in Version 0.3.0)

📍 خرائط المواقع الجديدة (New Position Mappings)

🆕 ما الجديد في الإصدار 0.2.0 (What's New in Version 0.2.0)

📍 خرائط المواقع الجديدة (New Position Mappings)

📖 Quran Transcript

🔧 Installation

🧠 Usage Examples

🕋 Aya Object

🔁 Loop Through All Surahs

🧮 Get Number of Verses per Surah

🔄 Convert Imlaey Script to Uthmani

🔤 Convert Uthmani Script to Phonetic Script

الرسم الصوتي للقرآن الكريم

📊 خرائط المواقع (Position Mappings)

فهم MappingPos (Understanding MappingPos)

📖 مثال على استخدام البحث الصوتي (Example of Phonetic Search)

📦 كائنات النتائج (Result Dataclasses)

PhonemesSearchSpan

PhonmesSearhResult

📖 مثال على تحليل أخطاء التلاوة (Error Analysis Example)

📦 كائنات تحليل الأخطاء (Error Analysis Dataclasses)

ReciterError

الحروف: (43)

صفات الحروف (10)

Needs refactory

Build for Source

Annotation Application of annotation imlaey to uthmnai

Quran Script Description

merge_uthmani_imlaey.py

TODO

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`quran-transcript` package

`PhonemesSearchSpan`

`PhonmesSearhResult`

`ReciterError`

`merge_uthmani_imlaey.py`

Packages