Arabic Tashkeel Processing

Relevant source files

The following files were used as context for generating this wiki page:

• src/piper/tashkeel/__init__.py
• tests/test_tashkeel.py
• src/piper/voice.py
• setup.py
• tests/test_piper.py

Arabic Tashkeel Processing in Piper is a specialized module designed to perform automatic diacritization (adding vowel marks) to Arabic text. This process is critical for accurate Text-to-Speech (TTS) synthesis in Arabic, as diacritics significantly alter the pronunciation and meaning of words. The implementation is a Python port of libtashkeel, utilizing a deep learning model to predict the correct marks based on context.

The module is integrated into the core synthesis pipeline, automatically activating when an Arabic voice is used. It processes raw Arabic strings into diacritized versions before they are passed to the phonemization engine, ensuring that the resulting speech is naturally articulated and grammatically correct.
Sources: src/piper/tashkeel/__init__.py:1-12, src/piper/voice.py:165-174, tests/test_tashkeel.py:1-5

System Architecture

The Tashkeel processing system relies on an ONNX-based inference model and a series of character mapping files. The TashkeelDiacritizer class serves as the primary interface, managing model loading, text preprocessing, and result reconstruction.

Core Components

The architecture consists of three main layers: the preprocessing layer which cleans and encodes text, the inference layer which uses onnxruntime to predict diacritics, and the post-processing layer which merges predictions back into the original text.

Implementation Details

The TashkeelDiacritizer Class

The TashkeelDiacritizer class is responsible for the end-to-end transformation of text. Upon initialization, it loads the neural network model and several JSON mapping files that define the vocabulary and diacritic types.

Component	File	Description
Inference Model	model.onnx	The pre-trained neural network for predicting diacritics.
Input Map	input_id_map.json	Maps Arabic characters to integer IDs for the model.
Target Map	target_id_map.json	Maps model output IDs back to Arabic diacritic characters.
Hint Map	hint_id_map.json	Used to process existing diacritics as hints for the model.

Sources: src/piper/tashkeel/__init__.py:33-59, setup.py:16-24

Processing Logic

The processing pipeline follows a specific sequence to handle text safely and efficiently:

1. Normalization: The text is stripped and checked against a character limit of 12,000 characters.
2. Character Filtering: Invalid characters are identified and temporarily removed, while numerals are replaced with a generic symbol (#).
3. Inference: The processed character IDs are sent to the ONNX session.
4. Annotation: The predicted diacritics are merged with the original text. If a taskeen_threshold is provided, the system can apply "Taskeen" (Sukoon at word ends) based on confidence logits.

def diacritize(self, text: str, taskeen_threshold=None) -> str:
    text = text.strip()
    if len(text) > CHAR_LIMIT:
        raise TashkeelError(f"Text length cannot exceed {CHAR_LIMIT}")

    input_text, removed_chars = self._to_valid_chars(text)
    input_text, diacritics = self._extract_chars_and_diacritics(
        input_text, normalize_diacritics=True
    )
    # ... model inference and reconstruction ...

Sources: src/piper/tashkeel/__init__.py:65-90

Integration with Piper Voice

The Tashkeel module is integrated into the PiperVoice class within voice.py. When the voice configuration indicates an Arabic language (ar), the synthesizer automatically invokes the diacritizer during the phonemization step.

Configuration Options

Users can control the Tashkeel behavior through the PiperVoice attributes:

• use_tashkeel: A boolean flag to enable or disable the processing (defaults to True).
• taskeen_threshold: A float (default 0.8) determining the confidence level for applying Sukoon.

Sources: src/piper/voice.py:108-111, tests/test_tashkeel.py:34-35

Character Handling and Constants

The module defines specific character sets and maps to handle the nuances of Arabic script, including various Harakat (diacritics).

Constant	Value / Definition	Purpose
CHAR_LIMIT	12,000	Maximum input length to prevent memory issues.
NUMERALS	0-9 and Arabic-Indic digits	Characters to be normalized to #.
HARAKAT_CHARS	\u064c to \u0652	Set of specific Arabic vowel marks.
SUKOON	\u0652	The "no vowel" mark used in Taskeen processing.

Sources: src/piper/tashkeel/__init__.py:15-25

Conclusion

Arabic Tashkeel Processing is a vital subsystem within Piper that bridges the gap between raw Arabic script and phonemic representation. By leveraging a dedicated ONNX model and robust character mapping, it ensures that Arabic speech synthesis maintains high linguistic accuracy. Its seamless integration into the PiperVoice pipeline allows for high-quality Arabic TTS with minimal configuration.