Release Ava 82M v0.1

Listener-selected Persian Kokoro Stage-2 Epoch-2 checkpoint with a one-call Python API, CLI, Persian frontend, default boundary cleanup, model card, licenses, hashes, and samples.

.gitattributes

@@ -1,35 +1,5 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
 *.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.wav filter=lfs diff=lfs merge=lfs -text
+*.whl filter=lfs diff=lfs merge=lfs -text
+

.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+.uv-cache/
+.cache/
+dist/
+outputs/
+ava.wav
+

CITATIONS.md

@@ -0,0 +1,52 @@
+# Citations
+
+## Mana-TTS
+
+```bibtex
+@inproceedings{qharabagh-etal-2025-manatts,
+  title = {{M}ana{TTS} {P}ersian: A Recipe for Creating {TTS} Datasets for Lower-Resource Languages},
+  author = {Qharabagh, Mahta Fetrat and Dehghanian, Zahra and Rabiee, Hamid R.},
+  booktitle = {Proceedings of the 2025 Conference of the North American Chapter of the Association for Computational Linguistics},
+  year = {2025},
+  publisher = {Association for Computational Linguistics},
+  pages = {9177--9206},
+  url = {https://aclanthology.org/2025.naacl-long.464/}
+}
+```
+
+## Homo-GE2PE
+
+```bibtex
+@misc{qharabagh2025fastfancyrethinkingg2p,
+  title = {Fast, Not Fancy: Rethinking G2P with Rich Data and Rule-Based Models},
+  author = {Mahta Fetrat Qharabagh and Zahra Dehghanian and Hamid R. Rabiee},
+  year = {2025},
+  eprint = {2505.12973},
+  archivePrefix = {arXiv},
+  primaryClass = {cs.CL},
+  url = {https://arxiv.org/abs/2505.12973}
+}
+```
+
+## StyleTTS2
+
+```bibtex
+@article{li2023styletts2,
+  title = {StyleTTS 2: Towards Human-Level Text-to-Speech through Style Diffusion and Adversarial Training with Large Speech Language Models},
+  author = {Li, Yinghao Aaron and Han, Cong and Raghavan, Vinay and Mischler, Gavin and Mesgarani, Nima},
+  journal = {arXiv preprint arXiv:2306.07691},
+  year = {2023}
+}
+```
+
+## iSTFTNet
+
+```bibtex
+@inproceedings{kaneko2022istftnet,
+  title = {iSTFTNet: Fast and Lightweight Mel-Spectrogram Vocoder Incorporating Inverse Short-Time Fourier Transform},
+  author = {Kaneko, Takuhiro and Tanaka, Kou and Kameoka, Hirokazu and Seki, Shogo},
+  booktitle = {ICASSP},
+  year = {2022}
+}
+```
+

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

NOTICE.md

@@ -0,0 +1,22 @@
+# Ava 82M notices
+
+Ava 82M is a Persian fine-tune of
+[hexgrad/Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M).
+Kokoro's weights and inference code are distributed under Apache License 2.0.
+
+The inference package pins the compatible
+[semidark/kokoro](https://github.com/semidark/kokoro) runtime at commit
+`b96fef95e6a746495f92443fac7c688f90fc57fc`.
+
+Fine-tuning audio was selected from
+[MahtaFetrat/Mana-TTS](https://huggingface.co/datasets/MahtaFetrat/Mana-TTS),
+released under CC0 1.0. The dataset creators request ethical use and expressly
+warn against voice impersonation, identity theft, and fraud.
+
+Persian grapheme-to-phoneme conversion uses
+[MahtaFetrat/Homo-GE2PE-Persian](https://huggingface.co/MahtaFetrat/Homo-GE2PE-Persian),
+released under the MIT License.
+
+Ava is released by Nimruz. “Ava” (آوا) means voice or sound in Persian.
+No affiliation with the upstream Kokoro or Mana-TTS authors is implied.
+

README.md

@@ -0,0 +1,203 @@
+---
+language:
+  - fa
+license: apache-2.0
+library_name: kokoro
+pipeline_tag: text-to-speech
+base_model: hexgrad/Kokoro-82M
+base_model_relation: finetune
+datasets:
+  - MahtaFetrat/Mana-TTS
+tags:
+  - persian
+  - farsi
+  - tts
+  - speech-synthesis
+  - kokoro
+  - styletts2
+  - accessibility
+---
+
+# Ava 82M (آوا)
+
+**Ava** is a lightweight, open-weight Persian text-to-speech model released by
+Nimruz. It is a Persian adaptation of
+[Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M), fine-tuned on an
+approximately 10-hour curated subset of
+[Mana-TTS](https://huggingface.co/datasets/MahtaFetrat/Mana-TTS).
+
+Ava produces 24 kHz, single-speaker Persian speech. The release includes a
+Persian text frontend, number/date normalization, contextual grapheme-to-phoneme
+conversion, pronunciation overrides, automatic long-text splitting, and
+conservative cleanup of leading and trailing synthesis artifacts.
+
+> **Status:** v0.1 research release. Manual listening found the model clear and
+> stable on conversational text, numbers, dates, and prices, but no formal MOS
+> or Persian intelligibility benchmark has been completed yet.
+
+## Quick start
+
+Python 3.11–3.13 and Git are required. Install the small Ava package directly
+from this repository:
+
+```bash
+python -m pip install \
+  "https://huggingface.co/xmanii/Ava-82M/resolve/main/ava_tts-0.1.0-py3-none-any.whl"
+```
+
+Then generate speech:
+
+```python
+from ava_tts import Ava
+
+tts = Ava()
+tts.save("سلام! من آوا هستم.", "ava.wav")
+```
+
+The first run downloads the 82M-parameter acoustic model and the pinned Persian
+G2P frontend. Later runs use the local cache.
+
+### Command line
+
+```bash
+ava "قیمت این محصول سه میلیون و چهارصد هزار تومان است." -o price.wav
+```
+
+Adjust speaking rate:
+
+```bash
+ava "امروز بیست و ششم تیر است." --speed 0.95 -o slower.wav
+```
+
+Boundary cleanup is enabled by default because listening tests found that it
+removes the short robotic noise that can occur before or after speech. To
+inspect the unprocessed model output:
+
+```bash
+ava "سلام، این خروجی خام مدل است." --raw-boundaries -o raw.wav
+```
+
+### Reuse one model for multiple utterances
+
+Loading the model once is faster:
+
+```python
+from ava_tts import Ava
+
+tts = Ava.from_pretrained("xmanii/Ava-82M")
+tts.save("این جملهٔ اول است.", "first.wav")
+tts.save("و این جملهٔ دوم است.", "second.wav", speed=1.05)
+```
+
+On the tested MacBook Air M4, CPU inference generated approximately 4.5 seconds
+of speech in roughly 0.9 seconds after loading. CPU is therefore selected
+automatically on Apple Silicon.
+
+## What is included
+
+| File | Purpose |
+|---|---|
+| `model.pth` | Selected Stage-2 Epoch-2 acoustic checkpoint |
+| `voice.pt` | Persian single-speaker style/voice tensor |
+| `config.json` | Kokoro architecture and phoneme vocabulary |
+| `pronunciations.json` | Reviewed pronunciation correction layer |
+| `ava_tts-0.1.0-py3-none-any.whl` | Friendly Python API and `ava` command |
+| `samples/ava-fa-sample.wav` | Boundary-cleaned example output |
+| `artifact_manifest.json` | File sizes, hashes, and provenance |
+
+The package pins the exact Kokoro runtime revision used during local and cloud
+validation. The public `kokoro==0.9.4` decoder is not weight-compatible with
+this checkpoint.
+
+## Architecture
+
+Ava retains Kokoro's compact StyleTTS2/iSTFTNet-derived inference architecture:
+
+1. Persian text is normalized, including Persian/Arabic digits, dates, times,
+   percentages, and common numeric forms.
+2. The pinned Homo-GE2PE model converts contextual Persian writing into
+   phonemes.
+3. Ava maps those phonemes into Kokoro's IPA vocabulary.
+4. The duration and prosody predictor estimates timing and pitch.
+5. The decoder/vocoder generates a 24 kHz waveform directly.
+6. Boundary-only cleanup trims synthesis artifacts without modifying internal
+   pauses.
+
+The acoustic network has **81,763,410 inference parameters**. The separate G2P
+frontend is not included in that parameter count.
+
+## Training and checkpoint selection
+
+- Base model: `hexgrad/Kokoro-82M`
+- Fine-tuning data: approximately 10 curated hours from `MahtaFetrat/Mana-TTS`
+- Training recipe: StyleTTS2/Kokoro two-stage fine-tuning
+- Released checkpoint: Stage 2, Epoch 2
+- Sample rate: 24 kHz
+- Voice count: one
+- Validation loss recorded at the selected checkpoint: `0.48536252975463867`
+
+The later joint-training experiment became numerically unstable and its
+listener-evaluated output was more robotic, so it was deliberately excluded.
+The released checkpoint is the best listener-approved artifact, not simply the
+last checkpoint produced.
+
+## Evaluation
+
+Evaluation for v0.1 is primarily structured human listening:
+
+- Pronunciation was substantially more intelligible than the untuned Kokoro
+  baseline.
+- Persian accent and phrasing improved over the short pilot.
+- Numbers, dates, and prices were intelligible after normalization.
+- Stage-2 Epoch 2 reduced most of the robotic tone heard in Stage 1.
+- Boundary cleanup removed the brief synthetic onset/ending artifact without
+  changing internal pauses.
+- Local output closely matched the cloud evaluation path after pinning the
+  exact runtime.
+
+Formal MOS, speaker-similarity, real-time-factor across platforms, and Persian
+phoneme-error-rate evaluations remain future work.
+
+## Limitations
+
+- Ava v0.1 has one voice and may preserve characteristics of the Mana-TTS
+  narrator.
+- Some uncommon names, loanwords, homographs, and specialized terminology can
+  still be mispronounced.
+- Tone can occasionally sound synthetic, and pace can vary.
+- Very long text is split automatically and may have noticeable joins.
+- The Persian frontend is a separate model, so first-run download and memory
+  use are larger than the 82M acoustic parameter count suggests.
+- The model has been tested most thoroughly on contemporary Iranian Persian.
+- This research release is not guaranteed for safety-critical use.
+
+## Responsible use
+
+Use Ava for ethical speech and accessibility applications. Do not use it for
+impersonation, identity theft, fraud, deception, harassment, or misleading
+claims that generated speech came from a real person. Clearly disclose
+synthetic speech where a listener could reasonably mistake it for authentic
+recorded speech.
+
+The Mana-TTS maintainers specifically prohibit impersonation, identity theft,
+and fraudulent use in their ethical-use notice.
+
+## License and attribution
+
+Ava code and weights are released under Apache License 2.0. See
+[`LICENSE`](./LICENSE) and [`NOTICE.md`](./NOTICE.md).
+
+This release depends on:
+
+- [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M), Apache-2.0.
+- [Mana-TTS](https://huggingface.co/datasets/MahtaFetrat/Mana-TTS), CC0-1.0.
+- [Homo-GE2PE-Persian](https://huggingface.co/MahtaFetrat/Homo-GE2PE-Persian),
+  MIT.
+- [StyleTTS2](https://github.com/yl4579/StyleTTS2).
+
+## Citation
+
+If you use Ava, please cite this repository as well as Kokoro, StyleTTS2,
+Mana-TTS, and Homo-GE2PE. Full upstream citations are included in
+[`CITATIONS.md`](./CITATIONS.md).
+

artifact_manifest.json

@@ -0,0 +1,55 @@
+{
+  "release": "Ava-82M-v0.1",
+  "repository": "xmanii/Ava-82M",
+  "publisher": "Nimruz",
+  "selected_checkpoint": "Stage-2 Epoch 2",
+  "source_checkpoint": "/output/pilot-10h-3plus3/epoch_2nd_00001.pth",
+  "source_epoch": 1,
+  "source_validation_loss": 0.48536252975463867,
+  "inference_parameters": 81763410,
+  "sample_rate": 24000,
+  "training_data_hours_approximate": 10,
+  "frontend": {
+    "normalizer": "ava-fa-v0.1",
+    "g2p_repository": "MahtaFetrat/Homo-GE2PE-Persian",
+    "g2p_revision": "9587f1e7966e41eaa0c514453cff7fb89db3473e",
+    "kokoro_runtime": "https://github.com/semidark/kokoro.git",
+    "kokoro_runtime_revision": "b96fef95e6a746495f92443fac7c688f90fc57fc"
+  },
+  "base_model": "hexgrad/Kokoro-82M",
+  "dataset": "MahtaFetrat/Mana-TTS",
+  "artifacts": {
+    "model.pth": {
+      "bytes": 327231582,
+      "sha256": "d60347fe3d8e47431c8eec2c0d44656fa19aa1b9a9360bbe0be3133fa4b6666d"
+    },
+    "voice.pt": {
+      "bytes": 523475,
+      "sha256": "15558df28cf358198b194b5ccb55241ff6a318badf11adf32346c5b3a08ca591"
+    },
+    "config.json": {
+      "bytes": 2351,
+      "sha256": "5abb01e2403b072bf03d04fde160443e209d7a0dad49a423be15196b9b43c17f"
+    },
+    "pronunciations.json": {
+      "bytes": 103,
+      "sha256": "0878f283f1b0340e6173fd51b7600a9bade6e22231feeef654ddc84151f7124e"
+    },
+    "ava_tts-0.1.0-py3-none-any.whl": {
+      "bytes": 20385,
+      "sha256": "258f7d533060ddbe4e408563037c491d91444f1070b3b216809f1b42c2c7454c"
+    },
+    "samples/ava-fa-sample.wav": {
+      "bytes": 191564,
+      "sha256": "8a90dd4a9e79d3c6babf38ad2f1999748735ceb96ac628c11b341e81e814c2d7"
+    },
+    "samples/ava-fa-release-smoke.wav": {
+      "bytes": 167084,
+      "sha256": "570d4dc43e261ca6f289cde3d680679ff3dfa467b8361be41dd0460d0d52e755"
+    },
+    "samples/ava-fa-wheel-smoke.wav": {
+      "bytes": 110444,
+      "sha256": "4dad33b0579731cd7e7dc19bf573074e6beb04f4e576802f0922fd1b591650df"
+    }
+  }
+}

config.json

@@ -0,0 +1,150 @@
+{
+  "istftnet": {
+    "upsample_kernel_sizes": [20, 12],
+    "upsample_rates": [10, 6],
+    "gen_istft_hop_size": 5,
+    "gen_istft_n_fft": 20,
+    "resblock_dilation_sizes": [
+      [1, 3, 5],
+      [1, 3, 5],
+      [1, 3, 5]
+    ],
+    "resblock_kernel_sizes": [3, 7, 11],
+    "upsample_initial_channel": 512
+  },
+  "dim_in": 64,
+  "dropout": 0.2,
+  "hidden_dim": 512,
+  "max_conv_dim": 512,
+  "max_dur": 50,
+  "multispeaker": true,
+  "n_layer": 3,
+  "n_mels": 80,
+  "n_token": 178,
+  "style_dim": 128,
+  "text_encoder_kernel_size": 5,
+  "plbert": {
+    "hidden_size": 768,
+    "num_attention_heads": 12,
+    "intermediate_size": 2048,
+    "max_position_embeddings": 512,
+    "num_hidden_layers": 12,
+    "dropout": 0.1
+  },
+  "vocab": {
+    ";": 1,
+    ":": 2,
+    ",": 3,
+    ".": 4,
+    "!": 5,
+    "?": 6,
+    "—": 9,
+    "…": 10,
+    "\"": 11,
+    "(": 12,
+    ")": 13,
+    "“": 14,
+    "”": 15,
+    " ": 16,
+    "\u0303": 17,
+    "ʣ": 18,
+    "ʥ": 19,
+    "ʦ": 20,
+    "ʨ": 21,
+    "ᵝ": 22,
+    "\uAB67": 23,
+    "A": 24,
+    "I": 25,
+    "O": 31,
+    "Q": 33,
+    "S": 35,
+    "T": 36,
+    "W": 39,
+    "Y": 41,
+    "ᵊ": 42,
+    "a": 43,
+    "b": 44,
+    "c": 45,
+    "d": 46,
+    "e": 47,
+    "f": 48,
+    "h": 50,
+    "i": 51,
+    "j": 52,
+    "k": 53,
+    "l": 54,
+    "m": 55,
+    "n": 56,
+    "o": 57,
+    "p": 58,
+    "q": 59,
+    "r": 60,
+    "s": 61,
+    "t": 62,
+    "u": 63,
+    "v": 64,
+    "w": 65,
+    "x": 66,
+    "y": 67,
+    "z": 68,
+    "ɑ": 69,
+    "ɐ": 70,
+    "ɒ": 71,
+    "æ": 72,
+    "β": 75,
+    "ɔ": 76,
+    "ɕ": 77,
+    "ç": 78,
+    "ɖ": 80,
+    "ð": 81,
+    "ʤ": 82,
+    "ə": 83,
+    "ɚ": 85,
+    "ɛ": 86,
+    "ɜ": 87,
+    "ɟ": 90,
+    "ɡ": 92,
+    "ɥ": 99,
+    "ɨ": 101,
+    "ɪ": 102,
+    "ʝ": 103,
+    "ɯ": 110,
+    "ɰ": 111,
+    "ŋ": 112,
+    "ɳ": 113,
+    "ɲ": 114,
+    "ɴ": 115,
+    "ø": 116,
+    "ɸ": 118,
+    "θ": 119,
+    "œ": 120,
+    "ɹ": 123,
+    "ɾ": 125,
+    "ɻ": 126,
+    "ʁ": 128,
+    "ɽ": 129,
+    "ʂ": 130,
+    "ʃ": 131,
+    "ʈ": 132,
+    "ʧ": 133,
+    "ʊ": 135,
+    "ʋ": 136,
+    "ʌ": 138,
+    "ɣ": 139,
+    "ɤ": 140,
+    "χ": 142,
+    "ʎ": 143,
+    "ʒ": 147,
+    "ʔ": 148,
+    "ˈ": 156,
+    "ˌ": 157,
+    "ː": 158,
+    "ʰ": 162,
+    "ʲ": 164,
+    "↓": 169,
+    "→": 171,
+    "↗": 172,
+    "↘": 173,
+    "ᵻ": 177
+  }
+}

inference.py

@@ -0,0 +1,10 @@
+"""Minimal local example after installing the Ava wheel."""
+
+from ava_tts import Ava
+
+tts = Ava.from_pretrained("xmanii/Ava-82M")
+tts.save(
+    "سلام! من آوا هستم، یک مدل سبک برای تبدیل متن فارسی به گفتار.",
+    "ava.wav",
+)
+

model.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d60347fe3d8e47431c8eec2c0d44656fa19aa1b9a9360bbe0be3133fa4b6666d
+size 327231582

pronunciations.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "word_overrides": {},
+  "full_text_overrides": {},
+  "phoneme_substitutions": {}
+}

pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "ava-tts"
+version = "0.1.0"
+description = "Ava: lightweight open Persian text-to-speech"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11,<3.14"
+authors = [{ name = "Nimruz" }]
+keywords = ["tts", "persian", "farsi", "speech", "kokoro"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "huggingface-hub>=0.34,<2",
+  "kokoro @ git+https://github.com/semidark/kokoro.git@b96fef95e6a746495f92443fac7c688f90fc57fc",
+  "numpy>=1.26,<3",
+  "sentencepiece>=0.2,<1",
+  "soundfile>=0.13,<1",
+  "torch>=2.6,<3",
+  "transformers>=4.51,<5",
+]
+
+[project.urls]
+Homepage = "https://huggingface.co/xmanii/Ava-82M"
+Repository = "https://huggingface.co/xmanii/Ava-82M"
+
+[project.scripts]
+ava = "ava_tts.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ava_tts"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[dependency-groups]
+dev = ["pytest>=8,<10"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

requirements.txt

@@ -0,0 +1,8 @@
+huggingface-hub>=0.34,<2
+kokoro @ git+https://github.com/semidark/kokoro.git@b96fef95e6a746495f92443fac7c688f90fc57fc
+numpy>=1.26,<3
+sentencepiece>=0.2,<1
+soundfile>=0.13,<1
+torch>=2.6,<3
+transformers>=4.51,<5
+

samples/README.md

@@ -0,0 +1,14 @@
+# Ava v0.1 samples
+
+All samples are 24 kHz mono PCM-16 WAV files with the default boundary cleanup.
+
+| File | Persian text |
+|---|---|
+| `ava-fa-sample.wav` | سلام، امروز می‌خواهم کیفیت مدل گفتار فارسی را بررسی کنم. |
+| `ava-fa-release-smoke.wav` | قیمت این کتاب سیصد و چهل و هشت هزار تومان است. |
+| `ava-fa-wheel-smoke.wav` | سلام از نسخهٔ نصب‌شدهٔ آوا. |
+
+The second and third files were generated through the final `Ava` API. The
+third was generated after unpacking the built wheel, exercising the same code
+users install from Hugging Face.
+

samples/ava-fa-release-smoke.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:570d4dc43e261ca6f289cde3d680679ff3dfa467b8361be41dd0460d0d52e755
+size 167084

samples/ava-fa-sample.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8a90dd4a9e79d3c6babf38ad2f1999748735ceb96ac628c11b341e81e814c2d7
+size 191564

samples/ava-fa-wheel-smoke.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4dad33b0579731cd7e7dc19bf573074e6beb04f4e576802f0922fd1b591650df
+size 110444

src/ava_tts/__init__.py

@@ -0,0 +1,7 @@
+"""Ava: lightweight open Persian text-to-speech."""
+
+from .model import Ava, Generation
+
+__all__ = ["Ava", "Generation"]
+__version__ = "0.1.0"
+

src/ava_tts/audio.py

@@ -0,0 +1,84 @@
+"""Optional boundary-only cleanup for generated waveforms."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class BoundaryCleanup:
+    audio: np.ndarray
+    trimmed_start_ms: float
+    trimmed_end_ms: float
+    threshold_db: float
+
+
+def _sustained_regions(mask: np.ndarray, required: int) -> tuple[int, int] | None:
+    if len(mask) < required:
+        return None
+    run = np.convolve(mask.astype(np.int16), np.ones(required, dtype=np.int16), mode="valid")
+    starts = np.flatnonzero(run == required)
+    if not len(starts):
+        return None
+    first = int(starts[0])
+    last = int(starts[-1] + required)
+    return first, last
+
+
+def clean_boundaries(
+    audio: np.ndarray,
+    sample_rate: int,
+    *,
+    threshold_db: float = -28.0,
+    frame_ms: float = 10.0,
+    hop_ms: float = 5.0,
+    sustained_ms: float = 20.0,
+    keep_ms: float = 70.0,
+    fade_ms: float = 12.0,
+) -> BoundaryCleanup:
+    """Trim only utterance edges; internal pauses are never modified."""
+
+    waveform = np.asarray(audio, dtype=np.float32).reshape(-1)
+    frame = max(1, round(sample_rate * frame_ms / 1000))
+    hop = max(1, round(sample_rate * hop_ms / 1000))
+    if len(waveform) < frame * 3:
+        return BoundaryCleanup(waveform.copy(), 0.0, 0.0, threshold_db)
+
+    starts = np.arange(0, len(waveform) - frame + 1, hop)
+    rms = np.array(
+        [
+            np.sqrt(np.mean(waveform[start : start + frame] ** 2) + 1e-12)
+            for start in starts
+        ],
+        dtype=np.float64,
+    )
+    peak = float(rms.max())
+    if peak <= 1e-8:
+        return BoundaryCleanup(waveform.copy(), 0.0, 0.0, threshold_db)
+    relative_db = 20 * np.log10(np.maximum(rms, 1e-12) / peak)
+    required = max(1, round(sustained_ms / hop_ms))
+    region = _sustained_regions(relative_db >= threshold_db, required)
+    if region is None:
+        return BoundaryCleanup(waveform.copy(), 0.0, 0.0, threshold_db)
+
+    first_frame, last_frame = region
+    keep = round(sample_rate * keep_ms / 1000)
+    start_sample = max(0, int(starts[first_frame]) - keep)
+    end_sample = min(len(waveform), int(starts[last_frame - 1]) + frame + keep)
+    if end_sample <= start_sample:
+        return BoundaryCleanup(waveform.copy(), 0.0, 0.0, threshold_db)
+
+    cleaned = waveform[start_sample:end_sample].copy()
+    fade = min(round(sample_rate * fade_ms / 1000), len(cleaned) // 4)
+    if fade:
+        ramp = np.sin(np.linspace(0, np.pi / 2, fade, dtype=np.float32)) ** 2
+        cleaned[:fade] *= ramp
+        cleaned[-fade:] *= ramp[::-1]
+    return BoundaryCleanup(
+        cleaned,
+        trimmed_start_ms=1000 * start_sample / sample_rate,
+        trimmed_end_ms=1000 * (len(waveform) - end_sample) / sample_rate,
+        threshold_db=threshold_db,
+    )

src/ava_tts/cli.py

@@ -0,0 +1,48 @@
+"""Command-line interface for Ava Persian TTS."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .model import Ava
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate Persian speech with Ava")
+    parser.add_argument("text", nargs="?", help="Persian text to speak")
+    parser.add_argument("--text-file", type=Path, help="read Persian text from a UTF-8 file")
+    parser.add_argument("-o", "--output", type=Path, default=Path("ava.wav"))
+    parser.add_argument("--speed", type=float, default=1.0)
+    parser.add_argument(
+        "--device",
+        choices=("auto", "cpu", "mps", "cuda"),
+        default="auto",
+    )
+    parser.add_argument(
+        "--raw-boundaries",
+        action="store_true",
+        help="disable the recommended leading/trailing artifact cleanup",
+    )
+    args = parser.parse_args()
+
+    text = args.text
+    if args.text_file:
+        text = args.text_file.read_text(encoding="utf-8")
+    if not text:
+        parser.error("provide Persian text or --text-file")
+
+    tts = Ava(device=args.device)
+    result = tts.generate(
+        text,
+        speed=args.speed,
+        cleanup=not args.raw_boundaries,
+    )
+
+    import soundfile as sf
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    sf.write(args.output, result.audio, result.sample_rate, subtype="PCM_16")
+    print(f"Saved {result.duration:.2f}s of speech to {args.output.resolve()}")
+    print(f"Device: {result.device}; segments: {len(result.phonemes)}")
+

src/ava_tts/frontend.py

@@ -0,0 +1,60 @@
+"""Pinned Homo-GE2PE to Kokoro phoneme conversion."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+_GE2PE_TO_IPA = {
+    "/": "æ",
+    "@": "ʔ",
+    "$": "ʃ",
+    "?": "ʔ",
+    "A": "ɒ",
+    "a": "ɒ",
+    "C": "ʧ",
+    "c": "ʧ",
+    "g": "ɡ",
+    "j": "ʤ",
+    "q": "ɣ",
+    "r": "ɾ",
+    "S": "ʃ",
+    "y": "j",
+    "Z": "ʒ",
+    "1": "",
+    "،": ",",
+    "؛": ";",
+    "؟": "?",
+    "ـ": "",
+    "\u200c": "",
+    "\u200f": "",
+    "\ufeff": "",
+    "-": " ",
+}
+_GE2PE_DIGRAPHS = {
+    "sh": "ʃ",
+    "zh": "ʒ",
+    "ch": "ʧ",
+    "kh": "x",
+    "gh": "ɣ",
+}
+
+
+def ge2pe_to_kokoro_ipa(value: str) -> str:
+    value = unicodedata.normalize("NFC", value.strip())
+    for digraph, ipa in _GE2PE_DIGRAPHS.items():
+        value = value.replace(digraph, ipa)
+    converted = "".join(_GE2PE_TO_IPA.get(character, character) for character in value)
+    return re.sub(r"\s+", " ", converted).strip()
+
+
+def validate_phonemes(phonemes: str, vocab: dict[str, int]) -> str:
+    if not phonemes.strip():
+        raise ValueError("phoneme sequence is empty")
+    if len(phonemes) > 510:
+        raise ValueError(f"phoneme sequence is {len(phonemes)} characters; maximum is 510")
+    unknown = sorted(set(phonemes) - set(vocab), key=ord)
+    if unknown:
+        detail = ", ".join(f"{item!r} U+{ord(item):04X}" for item in unknown)
+        raise ValueError(f"unsupported Kokoro phoneme symbols: {detail}")
+    return phonemes

src/ava_tts/g2p.py

@@ -0,0 +1,96 @@
+"""Pinned Persian grapheme-to-phoneme inference used by Ava."""
+
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+
+REPO_ID = "MahtaFetrat/Homo-GE2PE-Persian"
+REVISION = "9587f1e7966e41eaa0c514453cff7fb89db3473e"
+ARCHIVE = "model-weights/homo-ge2pe.zip"
+
+
+def _find_model(root: Path) -> Path:
+    candidates = sorted(
+        config.parent
+        for config in root.rglob("config.json")
+        if (config.parent / "tokenizer_config.json").exists()
+        or (config.parent / "spiece.model").exists()
+    )
+    if len(candidates) != 1:
+        raise RuntimeError(f"expected one G2P checkpoint under {root}, found {candidates}")
+    return candidates[0]
+
+
+def ensure_model(cache_dir: Path) -> Path:
+    """Download and safely extract the pinned G2P checkpoint once."""
+
+    from huggingface_hub import hf_hub_download
+
+    extracted = cache_dir / "homo-ge2pe" / REVISION
+    marker = extracted / ".complete"
+    if marker.exists():
+        return _find_model(extracted)
+    archive = Path(
+        hf_hub_download(
+            repo_id=REPO_ID,
+            filename=ARCHIVE,
+            revision=REVISION,
+            cache_dir=cache_dir / "huggingface",
+        )
+    )
+    extracted.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(archive) as handle:
+        root = extracted.resolve()
+        for member in handle.infolist():
+            destination = (extracted / member.filename).resolve()
+            if not destination.is_relative_to(root):
+                raise RuntimeError(f"unsafe G2P archive path: {member.filename}")
+        handle.extractall(extracted)
+    model = _find_model(extracted)
+    marker.write_text(str(model.relative_to(extracted)) + "\n", encoding="utf-8")
+    return model
+
+
+class PersianG2P:
+    """Lazy, reusable Homo-GE2PE frontend."""
+
+    def __init__(self, cache_dir: Path):
+        self.cache_dir = cache_dir
+        self._tokenizer = None
+        self._model = None
+
+    def _load(self) -> None:
+        if self._model is not None:
+            return
+        import torch
+        from transformers import AutoTokenizer, T5ForConditionalGeneration
+
+        model_dir = ensure_model(self.cache_dir)
+        self._tokenizer = AutoTokenizer.from_pretrained(model_dir)
+        self._model = T5ForConditionalGeneration.from_pretrained(
+            model_dir,
+            torch_dtype=torch.float32,
+        ).to("cpu").eval()
+
+    def __call__(self, text: str) -> str:
+        import torch
+
+        self._load()
+        encoded = self._tokenizer(
+            [text],
+            padding=True,
+            add_special_tokens=False,
+            return_attention_mask=True,
+            return_tensors="pt",
+        )
+        with torch.inference_mode():
+            output = self._model.generate(
+                **encoded,
+                num_beams=5,
+                min_length=1,
+                max_length=512,
+                early_stopping=True,
+            )
+        return self._tokenizer.batch_decode(output, skip_special_tokens=True)[0]
+

src/ava_tts/model.py

@@ -0,0 +1,252 @@
+"""High-level Persian text-to-speech API for Ava."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+
+from .audio import clean_boundaries
+from .frontend import ge2pe_to_kokoro_ipa, validate_phonemes
+from .g2p import PersianG2P
+from .pronunciation import apply_lexicon, load_lexicon
+from .text import normalize_persian
+
+DEFAULT_REPO_ID = "xmanii/Ava-82M"
+SAMPLE_RATE = 24_000
+MAX_PHONEMES = 510
+
+
+@dataclass(frozen=True)
+class Generation:
+    """Generated audio and the frontend decisions used to produce it."""
+
+    audio: np.ndarray
+    sample_rate: int
+    normalized_text: str
+    phonemes: tuple[str, ...]
+    device: str
+
+    @property
+    def duration(self) -> float:
+        return len(self.audio) / self.sample_rate
+
+
+def _select_device(requested: str) -> str:
+    import torch
+
+    if requested != "auto":
+        if requested == "mps" and not torch.backends.mps.is_available():
+            raise RuntimeError("MPS is not available")
+        if requested == "cuda" and not torch.cuda.is_available():
+            raise RuntimeError("CUDA is not available")
+        return requested
+    # The validated Kokoro decoder contains MPS fallbacks. On the tested M4,
+    # native CPU was around 13x faster than the MPS path.
+    if platform.system() == "Darwin" and platform.machine() == "arm64":
+        return "cpu"
+    if torch.cuda.is_available():
+        return "cuda"
+    return "cpu"
+
+
+def _default_cache() -> Path:
+    configured = os.environ.get("AVA_CACHE_DIR")
+    return Path(configured).expanduser() if configured else Path.home() / ".cache" / "ava-tts"
+
+
+class Ava:
+    """One-object interface for Persian text-to-speech."""
+
+    def __init__(
+        self,
+        repo_id: str = DEFAULT_REPO_ID,
+        *,
+        device: Literal["auto", "cpu", "mps", "cuda"] = "auto",
+        cache_dir: str | Path | None = None,
+        local_dir: str | Path | None = None,
+    ):
+        os.environ.setdefault("PYTORCH_ENABLE_MPS_FALLBACK", "1")
+        self.repo_id = repo_id
+        self.cache_dir = Path(cache_dir) if cache_dir else _default_cache()
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.device = _select_device(device)
+        self._g2p = PersianG2P(self.cache_dir)
+
+        paths = self._resolve_artifacts(Path(local_dir) if local_dir else None)
+        self._config = json.loads(paths["config"].read_text(encoding="utf-8"))
+        self._lexicon = load_lexicon(paths["lexicon"])
+
+        import torch
+        from kokoro import KModel
+
+        self._model = KModel(
+            repo_id="hexgrad/Kokoro-82M",
+            config=str(paths["config"]),
+            model=str(paths["model"]),
+            disable_complex=self.device == "mps",
+        ).to(self.device).eval()
+        self._voice = torch.load(
+            paths["voice"],
+            map_location="cpu",
+            weights_only=True,
+        )
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        repo_id: str = DEFAULT_REPO_ID,
+        **kwargs,
+    ) -> "Ava":
+        """Load Ava from Hugging Face."""
+
+        return cls(repo_id=repo_id, **kwargs)
+
+    def _resolve_artifacts(self, local_dir: Path | None) -> dict[str, Path]:
+        filenames = {
+            "model": "model.pth",
+            "voice": "voice.pt",
+            "config": "config.json",
+            "lexicon": "pronunciations.json",
+        }
+        if local_dir:
+            paths = {key: local_dir / filename for key, filename in filenames.items()}
+        else:
+            from huggingface_hub import hf_hub_download
+
+            paths = {
+                key: Path(
+                    hf_hub_download(
+                        repo_id=self.repo_id,
+                        filename=filename,
+                        cache_dir=self.cache_dir / "hub",
+                    )
+                )
+                for key, filename in filenames.items()
+            }
+        missing = [str(path) for path in paths.values() if not path.exists()]
+        if missing:
+            raise FileNotFoundError(f"missing Ava release artifacts: {missing}")
+        return paths
+
+    def _phonemize_normalized(self, normalized: str) -> str:
+        ge2pe = self._g2p(normalized)
+        result = apply_lexicon(normalized, ge2pe, self._lexicon)
+        return result.phonemes
+
+    @staticmethod
+    def _split_point(text: str) -> int:
+        """Choose a natural split close to the middle of a long utterance."""
+
+        middle = len(text) // 2
+        punctuation = [match.end() for match in re.finditer(r"[.!؟?!؛;،,]", text)]
+        spaces = [match.start() for match in re.finditer(r"\s+", text)]
+        candidates = [
+            point
+            for point in punctuation
+            if len(text) * 0.2 <= point <= len(text) * 0.8
+        ]
+        if not candidates:
+            candidates = [
+                point
+                for point in spaces
+                if len(text) * 0.2 <= point <= len(text) * 0.8
+            ]
+        return min(candidates, key=lambda point: abs(point - middle)) if candidates else -1
+
+    def phonemize(self, text: str) -> tuple[str, tuple[str, ...]]:
+        """Normalize and phonemize text, automatically splitting long input."""
+
+        normalized = normalize_persian(text, spoken=True)
+        if not normalized:
+            raise ValueError("text is empty")
+        pending = [normalized]
+        completed: list[str] = []
+        while pending:
+            piece = pending.pop(0).strip()
+            # Split conservatively before G2P generation can approach its own
+            # output limit. A later phoneme-length check remains authoritative.
+            if len(piece) > 350:
+                split = self._split_point(piece)
+                if split < 1:
+                    raise ValueError(
+                        "one text segment is too long and has no safe punctuation "
+                        "or word boundary"
+                    )
+                pending[0:0] = [piece[:split], piece[split:]]
+                continue
+            phonemes = self._phonemize_normalized(piece)
+            if len(phonemes) <= MAX_PHONEMES:
+                completed.append(validate_phonemes(phonemes, self._config["vocab"]))
+                continue
+            split = self._split_point(piece)
+            if split < 1:
+                raise ValueError(
+                    "one text segment exceeds Ava's 510-phoneme context window "
+                    "and has no safe punctuation or word boundary"
+                )
+            pending[0:0] = [piece[:split], piece[split:]]
+        return normalized, tuple(completed)
+
+    def generate(
+        self,
+        text: str,
+        *,
+        speed: float = 1.0,
+        cleanup: bool = True,
+        pause_ms: float = 120.0,
+    ) -> Generation:
+        """Generate 24 kHz mono audio from Persian text."""
+
+        if speed <= 0:
+            raise ValueError("speed must be greater than zero")
+        import torch
+
+        normalized, segments = self.phonemize(text)
+        waveforms: list[np.ndarray] = []
+        silence = np.zeros(round(SAMPLE_RATE * pause_ms / 1000), dtype=np.float32)
+        for index, phonemes in enumerate(segments):
+            reference = self._voice[len(phonemes) - 1].to(self.device)
+            with torch.inference_mode():
+                audio = self._model(phonemes, reference, speed=speed).numpy()
+            audio = np.asarray(audio, dtype=np.float32)
+            if cleanup:
+                audio = clean_boundaries(audio, SAMPLE_RATE).audio
+            if index:
+                waveforms.append(silence)
+            waveforms.append(audio)
+        joined = np.concatenate(waveforms) if waveforms else np.empty(0, dtype=np.float32)
+        return Generation(
+            audio=np.clip(joined, -1.0, 1.0),
+            sample_rate=SAMPLE_RATE,
+            normalized_text=normalized,
+            phonemes=segments,
+            device=self.device,
+        )
+
+    def save(
+        self,
+        text: str,
+        output: str | Path = "ava.wav",
+        **kwargs,
+    ) -> Path:
+        """Generate speech and save a PCM-16 WAV file."""
+
+        import soundfile as sf
+
+        destination = Path(output)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        generation = self.generate(text, **kwargs)
+        sf.write(
+            destination,
+            generation.audio,
+            generation.sample_rate,
+            subtype="PCM_16",
+        )
+        return destination.resolve()

src/ava_tts/pronunciation.py

@@ -0,0 +1,84 @@
+"""Reviewed pronunciation overrides layered on top of the pinned G2P."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .frontend import ge2pe_to_kokoro_ipa
+
+_EDGE_PUNCTUATION = "\"'()[]{}،؛:؟!,.…"
+
+
+@dataclass(frozen=True)
+class PronunciationResult:
+    phonemes: str
+    base_phonemes: str
+    applied: tuple[str, ...]
+
+
+def load_lexicon(path: Path) -> dict:
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if data.get("version") != 1:
+        raise ValueError(f"unsupported pronunciation lexicon version in {path}")
+    for key in ("word_overrides", "full_text_overrides", "phoneme_substitutions"):
+        if not isinstance(data.get(key), dict):
+            raise ValueError(f"{key} must be an object in {path}")
+    return data
+
+
+def _word_key(token: str) -> str:
+    return token.strip(_EDGE_PUNCTUATION)
+
+
+def _terminal_suffix(text_token: str, ipa_token: str) -> str:
+    if text_token.endswith(("؟", "?")) and ipa_token.endswith("ʔ"):
+        return "ʔ"
+    if text_token.endswith(("!", ".", "،", ",", "؛", ";", "…")):
+        match = re.search(r"([!.,;…])$", ipa_token)
+        return match.group(1) if match else ""
+    return ""
+
+
+def apply_lexicon(normalized_text: str, ge2pe: str, lexicon: dict) -> PronunciationResult:
+    base = ge2pe_to_kokoro_ipa(ge2pe)
+    full_override = lexicon["full_text_overrides"].get(normalized_text)
+    if full_override is not None:
+        return PronunciationResult(
+            phonemes=str(full_override),
+            base_phonemes=base,
+            applied=(f"full_text:{normalized_text}",),
+        )
+
+    text_tokens = normalized_text.split()
+    ge2pe_tokens = ge2pe.split()
+    ipa_tokens = [ge2pe_to_kokoro_ipa(token) for token in ge2pe_tokens]
+    applied: list[str] = []
+    word_overrides = lexicon["word_overrides"]
+    requested_words = {_word_key(token) for token in text_tokens} & set(word_overrides)
+    if requested_words and len(text_tokens) != len(ipa_tokens):
+        raise ValueError(
+            "cannot safely apply word pronunciation overrides because Persian "
+            f"and G2P token counts differ ({len(text_tokens)} != {len(ipa_tokens)})"
+        )
+    if len(text_tokens) == len(ipa_tokens):
+        for index, (text_token, ipa_token) in enumerate(zip(text_tokens, ipa_tokens, strict=True)):
+            key = _word_key(text_token)
+            if key not in word_overrides:
+                continue
+            suffix = _terminal_suffix(text_token, ipa_token)
+            ipa_tokens[index] = f"{word_overrides[key]}{suffix}"
+            applied.append(f"word:{key}")
+    phonemes = " ".join(ipa_tokens) if ipa_tokens else base
+
+    for old, new in lexicon["phoneme_substitutions"].items():
+        if old in phonemes:
+            phonemes = phonemes.replace(old, new)
+            applied.append(f"phoneme:{old}->{new}")
+    return PronunciationResult(
+        phonemes=phonemes,
+        base_phonemes=base,
+        applied=tuple(applied),
+    )

src/ava_tts/text.py

@@ -0,0 +1,175 @@
+"""Conservative Persian normalization used by the v0.1 training frontend."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+_CHAR_TRANSLATION = str.maketrans(
+    {
+        "ي": "ی",
+        "ى": "ی",
+        "ك": "ک",
+        "ۀ": "هٔ",
+        "ة": "ه",
+        "ـ": "",
+        "\u200b": "",
+        "\u200d": "",
+        "\ufeff": "",
+        "\u2066": "",
+        "\u2067": "",
+        "\u2068": "",
+        "\u2069": "",
+        "\u202a": "",
+        "\u202b": "",
+        "\u202c": "",
+        "\u202d": "",
+        "\u202e": "",
+    }
+)
+_DIGIT_TRANSLATION = str.maketrans(
+    "۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩",
+    "01234567890123456789",
+)
+_ONES = [
+    "صفر",
+    "یک",
+    "دو",
+    "سه",
+    "چهار",
+    "پنج",
+    "شش",
+    "هفت",
+    "هشت",
+    "نه",
+]
+_TEENS = [
+    "ده",
+    "یازده",
+    "دوازده",
+    "سیزده",
+    "چهارده",
+    "پانزده",
+    "شانزده",
+    "هفده",
+    "هجده",
+    "نوزده",
+]
+_TENS = ["", "", "بیست", "سی", "چهل", "پنجاه", "شصت", "هفتاد", "هشتاد", "نود"]
+_HUNDREDS = [
+    "",
+    "صد",
+    "دویست",
+    "سیصد",
+    "چهارصد",
+    "پانصد",
+    "ششصد",
+    "هفتصد",
+    "هشتصد",
+    "نهصد",
+]
+_SCALES = ["", "هزار", "میلیون", "میلیارد", "تریلیون", "کوادریلیون"]
+_NUMBER_RE = re.compile(
+    r"(?<![\w\u200c])(?P<sign>[+\-−])?"
+    r"(?P<number>\d[\d,٬]*(?:[./٫]\d+)?)(?P<percent>\s*[%٪])?"
+)
+_DATE_RE = re.compile(r"(?<!\d)(\d{2,4})[/-](\d{1,2})[/-](\d{1,2})(?!\d)")
+_TIME_RE = re.compile(r"(?<!\d)(?:ساعت\s*)?([01]?\d|2[0-3])\s*[:：]\s*([0-5]\d)(?!\d)")
+_LONG_DIGIT_SEQUENCE_RE = re.compile(r"(?<!\d)\d{7,17}(?!\d)")
+
+
+def _under_thousand(value: int) -> str:
+    parts: list[str] = []
+    hundreds, rest = divmod(value, 100)
+    if hundreds:
+        parts.append(_HUNDREDS[hundreds])
+    if rest < 10:
+        if rest:
+            parts.append(_ONES[rest])
+    elif rest < 20:
+        parts.append(_TEENS[rest - 10])
+    else:
+        tens, ones = divmod(rest, 10)
+        parts.append(_TENS[tens])
+        if ones:
+            parts.append(_ONES[ones])
+    return " و ".join(parts)
+
+
+def number_to_words(value: int) -> str:
+    if value == 0:
+        return _ONES[0]
+    if value < 0:
+        return f"منفی {number_to_words(-value)}"
+    if value >= 1000 ** len(_SCALES):
+        return " ".join(_ONES[int(digit)] for digit in str(value))
+    groups: list[str] = []
+    scale_index = 0
+    while value:
+        value, group = divmod(value, 1000)
+        if group:
+            spoken = _under_thousand(group)
+            scale = _SCALES[scale_index]
+            if scale_index == 1 and group == 1:
+                spoken = ""
+            groups.append(f"{spoken} {scale}".strip())
+        scale_index += 1
+    return " و ".join(reversed(groups))
+
+
+def _expand_numeric(match: re.Match[str]) -> str:
+    sign = match.group("sign")
+    token = match.group("number").translate(_DIGIT_TRANSLATION)
+    percent = bool(match.group("percent"))
+    token = token.replace(",", "").replace("٬", "")
+    separator = "/" if "/" in token else ("٫" if "٫" in token else ("." if "." in token else None))
+    if separator:
+        left, right = token.split(separator, 1)
+        right_words = (
+            number_to_words(int(right))
+            if separator == "/"
+            else " ".join(_ONES[int(digit)] for digit in right)
+        )
+        words = f"{number_to_words(int(left))} ممیز {right_words}"
+    else:
+        words = number_to_words(int(token))
+    if sign in {"-", "−"}:
+        words = f"منفی {words}"
+    elif sign == "+":
+        words = f"مثبت {words}"
+    return f"{words} درصد" if percent else words
+
+
+def normalize_persian(text: str, *, spoken: bool = True) -> str:
+    value = unicodedata.normalize("NFC", text).translate(_CHAR_TRANSLATION)
+    value = re.sub(r"[ \t\f\v]+", " ", value)
+    value = re.sub(r"\s+([،؛:؟!,.])", r"\1", value)
+    value = re.sub(r"([،؛:؟!])(?=\S)", r"\1 ", value)
+    if not spoken:
+        return value.strip()
+    value = value.translate(_DIGIT_TRANSLATION)
+    value = _DATE_RE.sub(
+        lambda match: (
+            f"سال {number_to_words(int(match.group(1)))}، "
+            f"ماه {number_to_words(int(match.group(2)))}، "
+            f"روز {number_to_words(int(match.group(3)))}"
+        ),
+        value,
+    )
+    value = _TIME_RE.sub(
+        lambda match: (
+            f"ساعت {number_to_words(int(match.group(1)))}"
+            + (
+                f" و {number_to_words(int(match.group(2)))} دقیقه"
+                if int(match.group(2))
+                else ""
+            )
+        ),
+        value,
+    )
+    value = _LONG_DIGIT_SEQUENCE_RE.sub(
+        lambda match: " ".join(_ONES[int(digit)] for digit in match.group()),
+        value,
+    )
+    value = _NUMBER_RE.sub(_expand_numeric, value)
+    return value.strip()

tests/test_audio.py

@@ -0,0 +1,33 @@
+import numpy as np
+
+from ava_tts.audio import clean_boundaries
+
+
+def test_cleanup_only_removes_edges_and_preserves_internal_pause():
+    sample_rate = 1000
+    edge_noise = np.full(200, 0.01, dtype=np.float32)
+    speech = np.full(300, 0.5, dtype=np.float32)
+    internal_pause = np.zeros(100, dtype=np.float32)
+    waveform = np.concatenate(
+        [edge_noise, speech, internal_pause, speech, edge_noise]
+    )
+    cleaned = clean_boundaries(
+        waveform,
+        sample_rate,
+        threshold_db=-20,
+        keep_ms=50,
+        fade_ms=10,
+    )
+    assert cleaned.trimmed_start_ms > 0
+    assert cleaned.trimmed_end_ms > 0
+    assert np.count_nonzero(cleaned.audio == 0) >= len(internal_pause)
+    assert len(cleaned.audio) < len(waveform)
+
+
+def test_cleanup_leaves_silence_unchanged():
+    silence = np.zeros(1000, dtype=np.float32)
+    cleaned = clean_boundaries(silence, 1000)
+    assert cleaned.trimmed_start_ms == 0
+    assert cleaned.trimmed_end_ms == 0
+    assert np.array_equal(cleaned.audio, silence)
+

tests/test_frontend.py

@@ -0,0 +1,28 @@
+import json
+from pathlib import Path
+
+from ava_tts.frontend import ge2pe_to_kokoro_ipa, validate_phonemes
+from ava_tts.text import normalize_persian
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_training_frontend_conversion():
+    assert ge2pe_to_kokoro_ipa("s/lAm") == "sælɒm"
+
+
+def test_spoken_normalization():
+    assert normalize_persian("قیمت ۱۲۳ تومان است.") == "قیمت صد و بیست و سه تومان است."
+
+
+def test_date_and_time_normalization():
+    normalized = normalize_persian("جلسه در ۱۴۰۵/۰۵/۰۴ ساعت 09:30 است.")
+    assert "سال هزار و چهارصد و پنج" in normalized
+    assert "ساعت نه و سی دقیقه" in normalized
+
+
+def test_config_accepts_persian_phonemes():
+    vocab = json.loads((ROOT / "config.json").read_text())["vocab"]
+    assert validate_phonemes("sælɒm", vocab) == "sælɒm"
+

tests/test_model.py

@@ -0,0 +1,24 @@
+from ava_tts.model import Ava
+
+
+def test_split_prefers_punctuation_near_middle():
+    text = "این بخش اول جمله است، و این بخش دوم جمله است."
+    split = Ava._split_point(text)
+    assert text[split - 1] == "،"
+
+
+def test_split_falls_back_to_word_boundary():
+    text = "یک متن بسیار طولانی برای آزمایش شکستن خودکار جمله"
+    split = Ava._split_point(text)
+    assert 0 < split < len(text)
+    assert text[split].isspace()
+
+
+def test_long_text_is_split_before_frontend_limit():
+    ava = object.__new__(Ava)
+    ava._config = {"vocab": {"a": 1}}
+    ava._phonemize_normalized = lambda text: "a" * len(text)
+    normalized, segments = ava.phonemize("واژه " * 120)
+    assert normalized
+    assert len(segments) > 1
+    assert all(len(segment) <= 510 for segment in segments)

tests/test_pronunciation.py

@@ -0,0 +1,33 @@
+import pytest
+
+from ava_tts.pronunciation import apply_lexicon
+
+
+def lexicon(**updates):
+    value = {
+        "version": 1,
+        "word_overrides": {},
+        "full_text_overrides": {},
+        "phoneme_substitutions": {},
+    }
+    value.update(updates)
+    return value
+
+
+def test_word_override_preserves_question_boundary():
+    result = apply_lexicon(
+        "سلام خوبی؟",
+        "s/lam khubi@",
+        lexicon(word_overrides={"خوبی": "xubi"}),
+    )
+    assert result.phonemes == "sælɒm xubiʔ"
+
+
+def test_ambiguous_alignment_fails_when_override_is_requested():
+    with pytest.raises(ValueError, match="cannot safely"):
+        apply_lexicon(
+            "سلام خوبی",
+            "s/lamkhubi",
+            lexicon(word_overrides={"خوبی": "xubi"}),
+        )
+

verify_release.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Verify the Ava release against artifact_manifest.json."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def main() -> None:
+    manifest = json.loads((ROOT / "artifact_manifest.json").read_text())
+    for filename, expected in manifest["artifacts"].items():
+        path = ROOT / filename
+        if not path.is_file():
+            raise SystemExit(f"missing: {filename}")
+        actual_size = path.stat().st_size
+        actual_hash = sha256(path)
+        if actual_size != expected["bytes"]:
+            raise SystemExit(
+                f"size mismatch for {filename}: {actual_size} != {expected['bytes']}"
+            )
+        if actual_hash != expected["sha256"]:
+            raise SystemExit(
+                f"hash mismatch for {filename}: {actual_hash} != {expected['sha256']}"
+            )
+        print(f"ok  {filename}  {actual_hash}")
+
+
+if __name__ == "__main__":
+    main()
+

voice.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:15558df28cf358198b194b5ccb55241ff6a318badf11adf32346c5b3a08ca591
+size 523475