tajweed-analyzer

Lightweight TypeScript library to analyze Qur'anic Arabic text and annotate Tajweed rules. It aims to be practical, readable, and easy to extend.

Features:

• Tokenization of Arabic letters and diacritics
• Rules covered (initial scope):
  • Noon Sakinah / Tanween: Izhar, Ikhfa, Idgham (with/without ghunnah), Iqlab
  • Meem Sakinah: Idgham Mimi, Ikhfa Shafawi, Izhar Shafawi
  • Qalqalah: ق ط ب ج د
  • Lam Shamsiyyah / Qamariyyah: after the definite article (ال)
  • Simple Madd Tabi'i
• Utilities to render annotated HTML with class names
• MIT licensed, contributions welcome

Install

npm install tajweed-analyzer
# or
pnpm add tajweed-analyzer
# or
yarn add tajweed-analyzer

Usage

import { analyze, renderAnnotatedHTML } from "tajweed-analyzer";

const input = "قُلْ أَعُوذُ بِرَبِّ النَّاسِ";
const res = analyze(input);
// res.annotations is an array of { start, end, type }

// Get simple HTML with CSS classes like .tajweed-ikhfa, .tajweed-iqlab, etc.
const html = renderAnnotatedHTML(res.text, res.annotations);

Add some CSS to see colors:

.tajweed-ikhfa {
  color: #1098ad;
}
.tajweed-idgham-with-ghunna {
  color: #2b8a3e;
}
.tajweed-idgham-without-ghunna {
  color: #2f9e44;
  text-decoration: underline;
}
.tajweed-iqlab {
  color: #d6336c;
}
.tajweed-izhar {
  color: #6c757d;
}
.tajweed-ikhfa-shafawi {
  color: #845ef7;
}
.tajweed-idgham-mimi {
  color: #e67700;
}
.tajweed-izhar-shafawi {
  color: #868e96;
}
.tajweed-qalqalah {
  color: #d9480f;
}
.tajweed-lam-shamsiyyah {
  background: rgba(253, 126, 20, 0.15);
}
.tajweed-lam-qamariyyah {
  background: rgba(33, 37, 41, 0.1);
}
.tajweed-madd-tabii {
  background: rgba(0, 123, 255, 0.15);
}

API

• analyze(text: string): { text, annotations }
  • Tokenizes the text and annotates spans with rule type.
  • type is one of:
    • "izhar", "ikhfa", "idgham-with-ghunna", "idgham-without-ghunna", "iqlab",
    • "ikhfa-shafawi", "idgham-mimi", "izhar-shafawi",
    • "qalqalah", "lam-shamsiyyah", "lam-qamariyyah", "madd-tabi'i".
• renderAnnotatedHTML(text, annotations): string
  • Renders span-wrapped HTML using .tajweed-${type} class names.
• tokenize(text): Token[]
  • Low-level tokenization helper (Arabic base + diacritics).

Accuracy & Scope

This library implements a practical subset of rules. It's not exhaustive; advanced madd types, waqf (stopping), tafkhim/tarqiq, and context-specific exceptions are not yet covered.

Contributions to expand coverage and improve accuracy are welcome.

Contributing

We welcome issues and PRs! Please:

• Open an issue describing the improvement/bug.
• Write clear descriptions and, if changing rule logic, include references where possible.
• Add unit tests (vitest/jest) to cover new logic.

Local development:

# from the repo root
cd packages/tajweed
npm install
npm run dev # or npm run build

Example app (Vite):

cd packages/tajweed/examples/vite-basic
npm install
npm run dev

Link into another project locally:

# in the consumer project
npm install ../path-to-repo/packages/tajweed
# or use npm link / pnpm link

Publishing:

cd packages/tajweed
npm publish --access public

License

MIT © Contributors