---
language:
- fa
license: apache-2.0
pipeline_tag: text-to-speech
tags:
- pytorch
- persian
- grainspeech
- hifi-gan
- experimental
- single-speaker
model_name: Gooya Microscopy v2 exp
base_model:
- Reza2kn/negara-g2p-clean-v7.1
datasets:
- Reza2kn/nasle-mana-clean-chunked-30s-avasanj
- Reza2kn/homorich-negara-gemini-tts-approved
- Reza2kn/homorich-negara-numeral-tts-approved-audio
---

# Gooya Microscopy v2 exp

Self-contained experimental Persian text-to-speech: **2,221,495 parameters**, including G2P, a contextual GrainSpeech acoustic model, and a tiny speaker-adapted HiFi-GAN vocoder. Produces 24 kHz mono WAV audio. The entire stack is included in this repository and runs offline after downloading and installing dependencies.

This is the stack used for the September 24 listening comparison. It includes the newer broad-corpus 837K student selected at epoch 16, not the earlier Nasle-only student. No Vocos, AvaSanj, training corpus, external checkpoint, Lightning, or remote inference service is required.

## Quick start

Python 3.10+; CPU is the default. CUDA is optional. PyTorch is a separate runtime dependency: the model weight size is not the installation size or peak RAM requirement. Old-device speed, Windows, mobile and browser inference have not been benchmarked.

```bash
python -m pip install huggingface_hub
hf download Reza2kn/Gooya-Microscopy-v2-exp --local-dir Gooya-Microscopy-v2-exp
python -m pip install -r Gooya-Microscopy-v2-exp/requirements.txt
python Gooya-Microscopy-v2-exp/infer.py --text "سلام، امروز حال شما چطوره؟" --output speech.wav
```

For a smaller CPU-only installation on Linux, install CPU PyTorch before the requirements:

```bash
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install -r Gooya-Microscopy-v2-exp/requirements.txt
```

To reproduce the included longer sample:

```bash
python Gooya-Microscopy-v2-exp/infer.py --text-file Gooya-Microscopy-v2-exp/examples/example.txt --output sample.wav
```

Pass `--device cuda` for GPU inference or `--threads 2` to limit CPU threads. The CLI also writes a JSON trace containing normalized text, generated phonemes, and segment durations. Model inference uses local files only. For fully offline use after setup, set `HF_HUB_OFFLINE=1` and `TRANSFORMERS_OFFLINE=1`.

## Python API

Install the included Python package once:

```bash
python -m pip install ./Gooya-Microscopy-v2-exp
```

```python
import soundfile as sf
from gooya_tts import GooyaTTS

model = GooyaTTS("Gooya-Microscopy-v2-exp", device="cpu")
audio, trace = model.synthesize("سلام، امروز حال شما چطوره؟", return_details=True)
sf.write("speech.wav", audio, model.sample_rate, subtype="FLOAT")

# Alternatively download the complete model snapshot explicitly:
# model = GooyaTTS.from_pretrained("Reza2kn/Gooya-Microscopy-v2-exp", device="cpu")
```

## Components and size

| Component | Parameters |
|---|---:|
| Distilled Negara student | 837,376 |
| Contextual GrainSpeech acoustic model | 437,685 |
| Tiny HiFi-GAN | 946,434 |
| **Total** | **2,221,495** |

Counts include fixed bins and weight-normalization parameters. Weights are FP32 safetensors; nominal parameter storage is about 8.89 MB, plus configs, tokenizer, code and examples. Training-only discriminators and optimizers are omitted. Exact file sizes and SHA-256 checksums are in `SHA256SUMS.json`.

## Inference behavior

The frontend deterministically expands supported number forms, then predicts case-sensitive Negara phonemes. Input is divided at commas, sentence punctuation and newlines. It adds 150 ms comma gaps and 300 ms sentence gaps, matching the listening comparison; these gaps are fixed rather than learned prosody. Acoustic durations, pitch and energy are predicted from phones. Tiny HiFi-GAN receives 100-bin mel features with hop 256 at 24 kHz.

The student uses greedy decoding and has no full Negara fallback. Inputs are not silently truncated. If G2P fails to emit EOS within 512 tokens or produces unsupported symbols, inference raises an error; use shorter phrases rather than accepting incomplete audio. Word-count disagreements produce a warning and remain visible in the trace. This is not a speech-completeness guarantee.

## Training and provenance

Acoustic/vocoder training uses the dataset's `label` field, not Koochik or Gemini ASR replacements. Source: [Nasle Mana](https://huggingface.co/datasets/Reza2kn/nasle-mana-clean-chunked-30s-avasanj), revision `606ecdc1d93a77c6f3a452ab5721774248cdf587`. After machine G2P/alignment filtering: 9,255 training excerpts / 19.10 hours and 2,337 development excerpts / 5.48 hours, with disjoint source recording groups. It did not consume every second of the source's approximately 41.4 labeled hours.

Architecture derives from [GrainSpeech](https://github.com/lab-emi/GrainSpeech), commit `8b38829809a6f86a9699371adc487c1efb875b05`, with a contextual bidirectional GRU, explicit boundary duration handling, and a 100-bin mel projection. The prosody variant trained for 50 epochs; the packaged best development checkpoint is step 10,413. The waveform generator derives from [HiFi-GAN V2](https://github.com/jik876/hifi-gan), with a new 100-mel input layer and 50,000 speaker-adaptation updates; selection used a fixed 96-excerpt development subset. See `provenance.json` for hashes and selected steps.

The G2P student was distilled from Negara v7.1 plus its overlay using Nasle Mana and the two HomoRich datasets listed above. Supplied phonemes were preserved separately from teacher targets. Deduplicated inputs and punctuation-delimited training clauses yielded 109,113 train, 7,358 development, and 4,969 reserved test examples after filtering. This particular 837K export has development results only; it is not being represented as independently test-qualified.

## Limitations

The 837K student has 13.04% phoneme character error against the Negara teacher on 7,358 development inputs (2.71% short, 22.32% medium, 35.86% long), with 38 nonterminating generations under that evaluation protocol. These are teacher-agreement metrics, not human pronunciation accuracy. This release remains experimental, particularly for long or unusual text.

User listening found the tiny vocoder acceptable for these samples, but speech can still be robotic. Proper names, colloquial spelling, ezafe, unfamiliar text, numbers, phrase boundaries and long inputs may fail. No MOS score, human pronunciation accuracy, real-time factor, memory ceiling, or device compatibility claim is made. A successful waveform or low training loss does not establish naturalness.

## Licensing and attribution

Release code and distributed modifications are Apache-2.0. Preserve the bundled Apache and MIT notices: GrainSpeech/EfficientSpeech and Negara use Apache-2.0; HiFi-GAN uses MIT. See `LICENSE`, `NOTICE`, and `licenses/`. Dataset copyrights and usage terms remain with their respective sources; this repository does not grant new rights to source recordings or imply speaker endorsement.

## Files

- `frontend/`: complete G2P model/tokenizer and overlay where applicable.
- `acoustic.safetensors`, `vocoder.safetensors`: inference-only weights.
- `gooya_config.json`, `gooya_tts/`, `infer.py`: standalone architecture, normalization, runtime and CLI.
- `examples/`: requested Persian sample and standalone output.
- `provenance.json`, `verification.json`, `SHA256SUMS.json`: provenance, verification receipt and integrity checks.