Bangla/Banglish STT-TTS R&D Project

This repository is now organized by responsibility so new contributors can quickly find what they need.

Directory Structure

• src/: core reusable modules
  • src/g2p/: grapheme-to-phoneme logic
  • src/services/: routing, decision, and handlers
  • src/utils/: text and token helpers
• rules/: normalization rule modules
• data/: source dictionaries and curated text datasets
  • data/abbreviation_dict.json, data/unit_dict.json, data/pronunciation_dict.json, etc.
  • data/corpora/: corpora CSV files used in story/audio generation
  • data/evaluation/: test-case/ground-truth text pairs
• ds/, ds_metadata/: audio benchmark dataset and metadata used for STT experiments
• experiments/: structured experiment outputs (step1_preprocessing, step2_asr, etc.)
• outputs/, demo_outputs/, jugantor_outputs/, story_outputs*/, one_line_outputs*/: generated media/results
• docs/: documentation and reports
  • docs/guides/: implementation and usage guides
  • docs/strategy/: experimentation strategies
  • docs/reports/phase1/: phase-1 reports
  • docs/reports/step/: step-specific results and comparisons
  • docs/notes/: archived notes
• reports/legacy/: JSON report artifacts historically written at root
• logs/: run logs
• scripts/: helper scripts and data preparation utilities
• steps/: step-by-step experiment instructions

Main Entry Points

• main.py: end-to-end normalization + TTS demo pipeline
• evaluate.py: text normalization evaluation (WER/CER and related metrics)
• run_advanced_demo.py: evaluation + demo audio generation
• run_jugantor_audio.py: batch Jugantor audio synthesis
• step1_preprocessing.py: Step-1 audio preprocessing benchmark
• step2_asr.py: Step-2 ASR model comparison benchmark
• run_stt_pipeline.py: STT backend implementations and evaluation helpers

Data File Locations (Updated)

• Default test cases: data/evaluation/test_cases.txt
• Default ground truth: data/evaluation/ground_truth.txt
• Demo test cases: data/evaluation/demo_v2_test_cases.txt
• Demo ground truth: data/evaluation/demo_v2_ground_truth.txt
• Jugantor test cases: data/evaluation/jugantor_test_cases.txt
• Bangla story words CSV: data/corpora/bangla_words.csv

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Run baseline evaluation

python evaluate.py

3. Run full TTS pipeline demo

python main.py

4. Run Step-1 and Step-2 experiments

python step1_preprocessing.py
python step2_asr.py --approaches 2E_indicwav2vec_bn

Contribution Guidance

• Keep reusable code in src/ or rules/.
• Keep experiments reproducible under experiments/<experiment_name>/.
• Keep new documentation under docs/ in the correct subfolder.
• Avoid adding new root-level files unless they are true project entry points.

STT Documentation

• docs/guides/stt_system_map.md: end-to-end map of the STT pipeline, datasets, folders, experiment status, and result locations.