Metadata-Version: 2.4
Name: uccharan
Version: 0.4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Typing :: Typed
Requires-Dist: pytest>=8 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
License-File: NOTICE
Summary: Phonemiser, text normaliser, transliterator and pronunciation engine for text-to-speech and speech recognition: 39 languages, Apache-2.0.
Keywords: g2p,phonemizer,tts,asr,text-normalization,transliteration,pronunciation,ipa,hindi,hinglish,piper,kokoro,sherpa-onnx
Author-email: Abhinav Gautam <abhinav@codebuckets.in>
License-Expression: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://cb-sigma.github.io/uccharan/
Project-URL: Issues, https://github.com/cB-Sigma/uccharan/issues
Project-URL: Repository, https://github.com/cB-Sigma/uccharan

# uccharan (Python)

**Phonemiser, text normaliser, transliterator and pronunciation engine** for text-to-speech and
speech recognition: 39 languages (English, Hindi, nineteen more South Asian languages and
seventeen European ones), in Rust, Python, JavaScript and C. Apache-2.0, no GPL code or data.
([what it does](https://github.com/cB-Sigma/uccharan#readme) ·
[measurements](https://github.com/cB-Sigma/uccharan/blob/main/docs/evaluation.md))

- **Phonemes** in the shapes Piper, Kokoro, Kitten TTS, Matcha-TTS and sherpa-onnx voices expect,
  compatible with the espeak-ng output those voices were trained on; an improved mode for voices
  you train yourself.
- **Normalise-only mode**: the spoken form of numbers, money, dates and URLs for voices that read
  text, with spans aligned to the input.
- **Transliteration** of romanised Hindi, Marathi, Bengali, Tamil, Telugu, Gujarati, Punjabi,
  Kannada and Malayalam into native script.
- **Pronunciation word lists**, **sound-alike matching** of a recogniser's output against your
  vocabulary, and **tools for training voices**.

```sh
uv add uccharan          # or: uv pip install uccharan
pip install uccharan
```

```python
import uccharan

uccharan.phonemize("Hello, world.")                          # 'həlˈoʊ, wˈɜːld.'
uccharan.phonemize("नमस्ते दुनिया", lang="hi")                  # 'nəmˈʌsteː dˈʊnɪjˌaː'
uccharan.phonemize("Hi there. Bye!", "en-us", "piper")       # ['hˈaɪ ðˈɛɹ.', 'bˈaɪ!']
uccharan.phonemize("Hi there.", "en-us", "sherpa-onnx")      # [[104, 712, 97, 618, …]]
uccharan.phonemize("I read it yesterday.", improved=True)    # 'aɪ ɹˈɛd ɪt jˈɛstɚdˌeɪ.'
uccharan.phonemize("I read the book.", "en-us", "kokoro")    # 'ˌI ɹˈɛd ðə bˈʊk.'  (misaki conventions, for Kokoro)
uccharan.phonemize_batch(lines, "hi")                        # all cores, GIL released

uccharan.normalize("Rs. 250 on 3/4/2024", "en-us").text      # 'two hundred fifty rupees on March fourth twenty twenty four'
uccharan.normalize("₹5 करोड़ का सौदा 10:30 बजे", "hi").text     # 'पांच करोड़ रुपये का सौदा साढ़े दस बजे'

uccharan.load_pack("xlit-hi")                                # CC BY-SA 4.0 pack, downloaded once
uccharan.transliterate("mujhe kal office jana hai", "hi").text   # 'मुझे कल office जाना है'

names = uccharan.SoundIndex(["Kothari", "Paytm"])
names.apply("send it to Coat Harry", "en-us").text           # 'send it to Kothari'
```

For code written against `phonemizer`:

```python
from uccharan.compat import EspeakBackend
backend = EspeakBackend("en-us", preserve_punctuation=True, with_stress=True)
backend.phonemize(["Hello, world."], strip=True)             # ['həlˈoʊ, wˈɜːld.']
```

A command-line program is installed as `uccharan` (`uccharan -l hi -p piper "नमस्ते"`).

Guides: [normalise-only mode](https://github.com/cB-Sigma/uccharan/blob/main/docs/normalize.md), [word lists](https://github.com/cB-Sigma/uccharan/blob/main/docs/wordlists.md),
[sound-alike matching](https://github.com/cB-Sigma/uccharan/blob/main/docs/soundalike.md), [transliteration](https://github.com/cB-Sigma/uccharan/blob/main/docs/transliteration.md),
[languages](https://github.com/cB-Sigma/uccharan/blob/main/docs/languages.md).

For training voices and checking pronunciation, `uccharan.train` and the `uccharan-train` command
label a dataset (training-ready phonemes for Piper, Matcha-TTS and icefall-style recipes, a symbol
table and a `voice.json`), choose a reading script, report phoneme and diphone coverage, and score
a recogniser's output against a reference word by word
([guide](https://github.com/cB-Sigma/uccharan/blob/main/docs/training.md)).

English for Kokoro uses a port of misaki with misaki 0.9.4's dictionaries; `load_misaki(dir)`
loads another copy.

The wheel (about 5 MB) carries the data of every language except British English. British
English and the Kokoro English data are language packs: downloaded from the GitHub release of the
same version the first time they are needed, checked against SHA-256 sums inside the wheel, and
cached in `~/.cache/uccharan`. On an offline machine put the `.ucd` files (from the release page)
in a directory named by `UCCHARAN_DATA_DIR`, set `UCCHARAN_OFFLINE=1` to forbid downloads, or call
`uccharan.load_pack(path)`. The transliteration packs (`xlit-hi`, …) and the Wiktionary packs
(`wikipron-en-us`, …) are CC BY-SA 4.0 and are fetched only when you call `load_pack` with their
name.

Documentation, measured agreement, speed and end-to-end results:
<https://github.com/cB-Sigma/uccharan>.

## Licence

Licence: Apache-2.0. Includes data from the CMU Pronouncing Dictionary (BSD-2-Clause) and misaki (Apache-2.0); see NOTICE.
The optional `wikipron-*` and `xlit-*` packs are CC BY-SA 4.0; they are separate downloads and are not part of this package.

