Telaffuz-YZ Thesis Repository

This repository contains the final research code, small validation data, figures, and the compiled thesis, paper, and slides for a Turkish pronunciation feedback pipeline.

The repository is intentionally lean. Large generated artifacts such as raw audio, full studio assessment caches, SQLite databases, parquet manifests, and model checkpoints are treated as external artifacts unless they are small enough and necessary for local smoke tests.

Pipeline

Turkish text
  -> rule-based G2P
  -> expected IPA phones
  -> wav2vec2 phone recognizer
  -> phone-level coach assessment (status + continuous score)
  -> conservative pronunciation feedback

The final system has four main parts:

Quick Start

uv sync
uv run g2p "merhaba"
uv run g2p --phones "ekmek"
uv run pytest

Focused checks:

PYTHONPATH=src uv run pytest tests/assess -q
uv run python scripts/eval_validation_recordings.py --limit 3
uv run python scripts/plot_wav2vec_per.py

Hugging Face Models

The released phoneme-CTC recognizers are published on Hugging Face. The Git repository keeps the code, configs, and small evaluation artifacts; model checkpoints remain external and are resolved locally through configs/models.toml.

Audio Pipeline CLI

The uv run audio <subcommand> command exposes the internal audio corpus pipeline (atlas building, forced alignment, dataset export, etc.). It is a research-only tool and requires a desktop GPU, external audio files, and the SQLite atlas database — none of which are committed to this repository. Run uv run audio --help for a full subcommand listing.

Reproducibility Scripts

Research scripts are run directly with uv run python scripts/...; they are not exposed as public console commands.

The coach endpoint is /api/v1/assess. For each target phone it returns a status (correct/incorrect/missing/extra), a continuous phonetic-distance score, separate non-gating quality and length channels, and diagnostics for the free decode.

Key Results

Why These Numbers Matter

• G2P at 1.48% PER establishes a reliable target-pronunciation producer. The remaining errors are concentrated in long-vowel lex gaps and loanword palatalization. These are documented blind spots: K1 only emits a non-punitive long-vowel cue, while palatal/velar evidence is handled by the K3 F2 rule.
• wav2vec PER is reported separately from coach feedback quality. The coach runtime treats recognizer identity evidence and atlas quality evidence as different signals.
• The validation set separates canonical, natural, and intended-wrong prompts so false positives and caught intended errors can be reported directly.
• MMS-1B is the default model alias for the runtime, with XLS-R kept as an alternate recognizer for comparison and diagnostics.

Repository Layout

configs/              coach runtime configs and model registry
data/g2p/             small G2P benchmark and lexical data
data/validation/      small assessment prompt and annotation tables
deliverables/         compiled thesis (PDF/DOCX), paper (PDF), and slides (HTML)
figures/              generated PNG figures
frontend/             single-page Vite + React demo frontend
scripts/              reproducibility and figure-generation scripts
src/g2p/              Turkish G2P package
src/audio/            audio corpus, alignment, and atlas helpers
src/assess/           phone-level coach assessment package (status + score)
src/api/              FastAPI demo backend (5 endpoints under /api/v1)
tests/                focused regression tests

Artifact Policy

Committed data is limited to small tables and final-facing documentation. Large or machine-generated artifacts stay outside Git:

Citation

@software{telaffuz_yz,
  title = {Telaffuz-YZ: Turkish Pronunciation Feedback Pipeline},
  author = {Onur Neşvat},
  year = {2026},
  note = {Master's thesis research repository}
}