altatts 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. altatts-2.0.0/PKG-INFO +315 -0
  2. altatts-2.0.0/PYPI_README.md +268 -0
  3. altatts-2.0.0/README.md +196 -0
  4. altatts-2.0.0/altatts/__init__.py +106 -0
  5. altatts-2.0.0/altatts/audio.py +324 -0
  6. altatts-2.0.0/altatts/benchmark.py +165 -0
  7. altatts-2.0.0/altatts/client.py +94 -0
  8. altatts-2.0.0/altatts/config.py +456 -0
  9. altatts-2.0.0/altatts/datasets/__init__.py +24 -0
  10. altatts-2.0.0/altatts/datasets/adapters.py +339 -0
  11. altatts-2.0.0/altatts/datasets/cli.py +77 -0
  12. altatts-2.0.0/altatts/datasets/combine.py +803 -0
  13. altatts-2.0.0/altatts/datasets/registry.py +120 -0
  14. altatts-2.0.0/altatts/datasets/spec.py +53 -0
  15. altatts-2.0.0/altatts/datasets/stats.py +241 -0
  16. altatts-2.0.0/altatts/deploy.py +235 -0
  17. altatts-2.0.0/altatts/env/__init__.py +2 -0
  18. altatts-2.0.0/altatts/env/checks.py +703 -0
  19. altatts-2.0.0/altatts/env/compat.py +194 -0
  20. altatts-2.0.0/altatts/env/compat_table.json +28 -0
  21. altatts-2.0.0/altatts/env/distributed.py +130 -0
  22. altatts-2.0.0/altatts/env/doctor.py +256 -0
  23. altatts-2.0.0/altatts/env/fix.py +465 -0
  24. altatts-2.0.0/altatts/env/wheels.py +301 -0
  25. altatts-2.0.0/altatts/export.py +186 -0
  26. altatts-2.0.0/altatts/inference/__init__.py +13 -0
  27. altatts-2.0.0/altatts/inference/checkpoint.py +115 -0
  28. altatts-2.0.0/altatts/inference/evaluate.py +316 -0
  29. altatts-2.0.0/altatts/inference/streaming.py +174 -0
  30. altatts-2.0.0/altatts/inference/synthesize.py +148 -0
  31. altatts-2.0.0/altatts/inference/synthesizer.py +431 -0
  32. altatts-2.0.0/altatts/inference/voices.py +120 -0
  33. altatts-2.0.0/altatts/integrations/__init__.py +21 -0
  34. altatts-2.0.0/altatts/integrations/callcenter.py +220 -0
  35. altatts-2.0.0/altatts/languages/__init__.py +261 -0
  36. altatts-2.0.0/altatts/languages/english.py +79 -0
  37. altatts-2.0.0/altatts/languages/french.py +99 -0
  38. altatts-2.0.0/altatts/languages/kinyarwanda.py +114 -0
  39. altatts-2.0.0/altatts/languages/swahili.py +86 -0
  40. altatts-2.0.0/altatts/lexicon.py +298 -0
  41. altatts-2.0.0/altatts/main_cli.py +86 -0
  42. altatts-2.0.0/altatts/metrics.py +300 -0
  43. altatts-2.0.0/altatts/model/__init__.py +19 -0
  44. altatts-2.0.0/altatts/model/latent.py +129 -0
  45. altatts-2.0.0/altatts/model/losses.py +64 -0
  46. altatts-2.0.0/altatts/model/meanflow.py +305 -0
  47. altatts-2.0.0/altatts/model/modules.py +184 -0
  48. altatts-2.0.0/altatts/model/monotonic_align.py +108 -0
  49. altatts-2.0.0/altatts/model/style.py +96 -0
  50. altatts-2.0.0/altatts/model/text_encoder.py +177 -0
  51. altatts-2.0.0/altatts/model/vits.py +327 -0
  52. altatts-2.0.0/altatts/model/waveform.py +159 -0
  53. altatts-2.0.0/altatts/recipes/__init__.py +43 -0
  54. altatts-2.0.0/altatts/recipes/multilingual_callcenter.json +219 -0
  55. altatts-2.0.0/altatts/serving.py +507 -0
  56. altatts-2.0.0/altatts/speaker/__init__.py +2 -0
  57. altatts-2.0.0/altatts/speaker/enroll.py +249 -0
  58. altatts-2.0.0/altatts/speaker/enroll_cli.py +74 -0
  59. altatts-2.0.0/altatts/tags.py +338 -0
  60. altatts-2.0.0/altatts/text.py +547 -0
  61. altatts-2.0.0/altatts/training/__init__.py +25 -0
  62. altatts-2.0.0/altatts/training/anonymize.py +459 -0
  63. altatts-2.0.0/altatts/training/data.py +585 -0
  64. altatts-2.0.0/altatts/training/launch.py +164 -0
  65. altatts-2.0.0/altatts/training/logging.py +381 -0
  66. altatts-2.0.0/altatts/training/prepare.py +595 -0
  67. altatts-2.0.0/altatts/training/segment.py +439 -0
  68. altatts-2.0.0/altatts/training/train.py +324 -0
  69. altatts-2.0.0/altatts/training/trainer.py +779 -0
  70. altatts-2.0.0/altatts/utils.py +219 -0
  71. altatts-2.0.0/altatts/voices_cli.py +91 -0
  72. altatts-2.0.0/altatts.egg-info/PKG-INFO +315 -0
  73. altatts-2.0.0/altatts.egg-info/SOURCES.txt +87 -0
  74. altatts-2.0.0/altatts.egg-info/dependency_links.txt +1 -0
  75. altatts-2.0.0/altatts.egg-info/entry_points.txt +15 -0
  76. altatts-2.0.0/altatts.egg-info/requires.txt +42 -0
  77. altatts-2.0.0/altatts.egg-info/top_level.txt +1 -0
  78. altatts-2.0.0/pyproject.toml +78 -0
  79. altatts-2.0.0/setup.cfg +4 -0
  80. altatts-2.0.0/tests/test_config_and_data.py +97 -0
  81. altatts-2.0.0/tests/test_datasets_pipeline.py +117 -0
  82. altatts-2.0.0/tests/test_doctor.py +178 -0
  83. altatts-2.0.0/tests/test_logging_early_stop.py +135 -0
  84. altatts-2.0.0/tests/test_model.py +176 -0
  85. altatts-2.0.0/tests/test_per_category_validation.py +46 -0
  86. altatts-2.0.0/tests/test_serving.py +192 -0
  87. altatts-2.0.0/tests/test_text_frontend.py +143 -0
  88. altatts-2.0.0/tests/test_voice_plan.py +64 -0
  89. altatts-2.0.0/tests/test_wheels.py +129 -0
altatts-2.0.0/PKG-INFO ADDED
@@ -0,0 +1,315 @@
1
+ Metadata-Version: 2.4
2
+ Name: altatts
3
+ Version: 2.0.0
4
+ Summary: ALTATTS: natural, expressive, multilingual text-to-speech with zero-shot voice cloning, emotion and pause control, anonymized default voices and a MeanFlow prior -- built for Kinyarwanda (plus English, French, Swahili code-switching), reusable for any language, call-center ready.
5
+ Author: YaliLabs / ALTA Project
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/yalilabs/altatts
8
+ Keywords: text-to-speech,tts,kinyarwanda,swahili,french,english,code-switching,voice-cloning,zero-shot,emotion,vits,meanflow,flow-matching,hifi-gan,speech-synthesis,call-center,telephony,streaming,low-resource
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
11
+ Classifier: Operating System :: OS Independent
12
+ Requires-Python: >=3.9
13
+ Description-Content-Type: text/markdown
14
+ Requires-Dist: torch>=2.3
15
+ Requires-Dist: torchaudio>=2.3
16
+ Requires-Dist: numpy>=1.24
17
+ Requires-Dist: soundfile>=0.12
18
+ Requires-Dist: tqdm>=4.66
19
+ Provides-Extra: av
20
+ Requires-Dist: av>=11.0; extra == "av"
21
+ Provides-Extra: asr
22
+ Requires-Dist: altasr>=1.1; extra == "asr"
23
+ Provides-Extra: onnx
24
+ Requires-Dist: onnx>=1.15; extra == "onnx"
25
+ Requires-Dist: onnxruntime>=1.17; extra == "onnx"
26
+ Provides-Extra: mms
27
+ Requires-Dist: transformers>=4.40; extra == "mms"
28
+ Provides-Extra: fast
29
+ Requires-Dist: numba>=0.58; extra == "fast"
30
+ Provides-Extra: data
31
+ Requires-Dist: pyarrow>=14; extra == "data"
32
+ Requires-Dist: openpyxl>=3.1; extra == "data"
33
+ Provides-Extra: logs
34
+ Requires-Dist: tensorboard>=2.14; extra == "logs"
35
+ Requires-Dist: matplotlib>=3.7; extra == "logs"
36
+ Provides-Extra: dev
37
+ Requires-Dist: pytest>=8.0; extra == "dev"
38
+ Provides-Extra: all
39
+ Requires-Dist: av>=11.0; extra == "all"
40
+ Requires-Dist: altasr>=1.1; extra == "all"
41
+ Requires-Dist: onnx>=1.15; extra == "all"
42
+ Requires-Dist: onnxruntime>=1.17; extra == "all"
43
+ Requires-Dist: transformers>=4.40; extra == "all"
44
+ Requires-Dist: numba>=0.58; extra == "all"
45
+ Requires-Dist: pyarrow>=14; extra == "all"
46
+ Requires-Dist: openpyxl>=3.1; extra == "all"
47
+
48
+ # ALTATTS
49
+
50
+ **Natural, expressive, multilingual text-to-speech with zero-shot voice cloning. Built for Kinyarwanda; speaks English, French and Swahili too; ready for call centers; one command to serve as an API.**
51
+
52
+ ALTATTS is the speaking half of the ALTA stack: [ALTASR](https://pypi.org/project/altasr/) listens, ALTATTS talks.
53
+
54
+ | capability | how |
55
+ |---|---|
56
+ | Natural prosody | **MeanFlow latent prior** (Geng, Deng, Bai, Kolter & He, 2025): the whole utterance is generated jointly in 1–4 steps |
57
+ | Word-exact speech | deterministic durations + monotonic alignment: no skipped or repeated words |
58
+ | Emotion and intensity | `emotion="happy", intensity=0.7` or inline `[calm]`, `[excited:0.8]` |
59
+ | Human behaviour | exact `[pause:0.5]`, natural `[pause]`, `[laugh]`, `[breath]`, `[sigh]`, hesitations |
60
+ | Voice cloning | enroll a speaker from a few seconds of audio, use it immediately, no training |
61
+ | Privacy | 12 anonymized **production voices** (French, English, Bantu groups: 2 F + 2 M each) that match no training speaker |
62
+ | Code-switching | Kinyarwanda, English, French, Swahili in one model, word-level language detection, per-language number reading |
63
+ | Telephony | 8 kHz G.711 μ-law / A-law, 20 ms frames, Twilio messages, phrase streaming |
64
+ | Serving | `altatts serve` (REST + WebSocket, standard library only) and `altatts package` (Docker folder, `docker compose up`) |
65
+ | Anywhere | CPU, one GPU, all GPUs, several machines; `altatts doctor --fix` repairs PyTorch/CUDA/audio installs |
66
+
67
+ Every ALTATTS 0.1 interface still works and 0.1 checkpoints load unchanged.
68
+
69
+ ---
70
+
71
+ ## 1. Install and check
72
+
73
+ ```bash
74
+ pip install "altatts[av]" # av = mp3/webm/opus decoding; "altatts[all]" for everything
75
+ altatts doctor # Python / torch / CUDA / audio deps -> PASS/WARN/FAIL + fixes
76
+ altatts doctor --fix # repair what is safe (matched torch for your driver, missing deps)
77
+ ```
78
+
79
+ A plain `pip install torch` pulls the newest CUDA build (cu130 today), which
80
+ does not run on older drivers (a 570.x driver supports CUDA ≤ 12.8).
81
+ `altatts doctor --fix` cross-checks the driver's ceiling, the GPU's
82
+ compute-capability floor and the wheels actually published for your Python
83
+ and CPU architecture, prints the choice, installs the newest torch the
84
+ machine can run (exact pins, right index), re-verifies CUDA and rolls back
85
+ on failure. `--fix --dry-run` shows the cross-check without changing
86
+ anything; `--index-url cu126` forces an index. The manual equivalent:
87
+
88
+ ```bash
89
+ pip install --force-reinstall "torch==2.14.1+cu126" torchaudio --index-url https://download.pytorch.org/whl/cu126
90
+ python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
91
+ ```
92
+
93
+ ## 2. Which model do I have? ("generation")
94
+
95
+ A model folder's `config.json` carries `"model": {"version": N}`. This is only a **generation number**, never something you set by hand:
96
+
97
+ | generation | what it means | cloning / emotions / MeanFlow |
98
+ |---|---|---|
99
+ | **ALTATTS 2** (`version: 2`) | trained with altatts ≥ 2.0 | yes |
100
+ | **ALTATTS 0.1 (legacy)** (no `version` key) | trained with altatts 0.1, plain VITS | no, but every 0.1 call still works |
101
+
102
+ ```python
103
+ tts.capabilities()["generation"] # 'ALTATTS 2' or 'ALTATTS 0.1 (legacy VITS)'
104
+ ```
105
+
106
+ Upgrade a 0.1 model by fine-tuning: `altatts-train --init-from runs/old_model --preset base ...` (all VITS weights are reused).
107
+
108
+ ## 3. Synthesize
109
+
110
+ ```python
111
+ from altatts import Synthesizer
112
+
113
+ tts = Synthesizer.from_pretrained("runs/kin_v2")
114
+ wav, sr = tts.tts("Muraho! Amakuru yawe?", voice="female") # the 0.1 call
115
+ tts.tts_to_file("Murakaza neza.", "hello.wav", voice="male", sample_rate=8000)
116
+ print(tts.voices()) # production voices, enrolled voices, aliases
117
+ print(tts.capabilities()) # generation, emotions, languages, cloning, pause token ...
118
+ ```
119
+
120
+ ### Every control, and the value that works best
121
+
122
+ | parameter | values | best practice |
123
+ |---|---|---|
124
+ | `voice` | `female`, `male`, `bantu_female_1`, `french_male_2`, `english_female_1`, `fr_female`, `kin_male`, an enrolled name, a training speaker, **or a path to a reference clip** | pick the group that matches the sentence language; `female`/`male` are the primary-language voices |
125
+ | `emotion` | `neutral happy sad angry fearful surprised disgusted calm excited` | `calm` for service lines, `happy` for greetings; only emotions seen in training have an effect (`capabilities()["emotions_seen_in_training"]`) |
126
+ | `intensity` | 0–1 | 0.3 subtle, **0.6 natural**, 1.0 strong |
127
+ | `speed` | 0.5–2 | **1.0**; 0.95 for instructions/health lines, 1.05–1.1 for busy IVR menus |
128
+ | `noise_scale` | 0–1 | **0.667** (standard); 0.5 for maximally consistent prompts, 0.8 for lively narration |
129
+ | `steps` | 1–8 | **4** default; 1 = fastest (CPU/live), 8 = maximum naturalness for pre-rendered media |
130
+ | `cfg_scale` | 1–2 | **1.0**; 1.3–1.8 amplifies a cloned identity or an emotion |
131
+ | `seed` | int | set it for reproducible prompts (same text → same audio) |
132
+ | `sample_rate` | 8000 … 48000 | 8000 telephony, 16000 ASR/voice bots, 22050 native, 48000 media |
133
+ | `language` | `rw en fr sw` (`kin eng fra swa` accepted) | set it for a monolingual non-primary sentence; mixed text is detected word by word; force spans with `<en>…</en>` |
134
+ | `pause_scale` | float | multiplies every `[pause:x]` |
135
+ | `reference_audio` (+ `reference_sr` for arrays) | path, array, `(array, sr)` or a list of clips | one-off cloning from a clip; 10–30 s of clean speech works best |
136
+ | `speaker_embedding` | vector from `tts.embed_speaker(...)` | fastest repeated cloning (embed once, reuse) |
137
+ | `prior` | `meanflow` / `flow` | `flow` = the 0.1 sampler, only for A/B comparisons |
138
+
139
+ ### Scenarios with their best configurations
140
+
141
+ ```python
142
+ # A. Call-center / IVR prompts (pre-rendered, 8 kHz, identical every time)
143
+ wav, sr = tts.tts("Murakaza neza kuri banki yacu. [pause:0.4] Kanda rimwe ku konti yawe.",
144
+ voice="bantu_female_1", emotion="calm", intensity=0.5,
145
+ speed=0.97, noise_scale=0.5, steps=8, seed=1, sample_rate=8000)
146
+ ulaw = tts.mulaw_bytes("Murakoze guhamagara.", voice="female", emotion="calm", seed=1)
147
+
148
+ # B. Live voice agent (lowest latency; stream phrase by phrase, see §5)
149
+ wav, sr = tts.tts("Yego, ndabikora nonaha.", voice="female", steps=2, sample_rate=16000)
150
+
151
+ # C. Media / audiobook narration (maximum naturalness)
152
+ wav, sr = tts.tts("Umwana yarahagurutse, [breath] areba hirya no hino, [pause:0.8] "
153
+ "maze aratangira kwiruka.", voice="bantu_male_2", emotion="excited",
154
+ intensity=0.6, noise_scale=0.8, steps=8, sample_rate=48000)
155
+
156
+ # D. Emotion sweep (faint -> ecstatic) on the same sentence
157
+ for inten in (0.2, 0.5, 0.8, 1.0):
158
+ wav, sr = tts.tts("Twishimiye cyane kubabona!", voice="female",
159
+ emotion="happy", intensity=inten, cfg_scale=1.3, seed=3)
160
+
161
+ # E. Code-switching and numbers (read in each sentence's language)
162
+ wav, sr = tts.tts("Konti yawe ifite FRW 2,500. <en>Your balance is 2,500 francs.</en> "
163
+ "Votre solde est de 2500 FRW. Salio lako ni FRW 2500.",
164
+ voice="bantu_female_2", steps=4)
165
+ wav, sr = tts.tts("Bonjour, votre dossier est prêt.", voice="french_female_1", language="fr")
166
+ wav, sr = tts.tts("Habari, akaunti yako iko tayari.", voice="bantu_male_1", language="sw")
167
+
168
+ # F. Human behaviour tags
169
+ wav, sr = tts.tts("Hmm [hesitation] ndabona. [pause:0.6] [laugh] Nibyo rwose! [breath] Reka nkwereke.",
170
+ voice="male", emotion="happy", intensity=0.5)
171
+
172
+ # G. Cloning: one-off, by path, enrolled
173
+ wav, sr = tts.tts("Muraho neza.", reference_audio=["agent_1.wav", "agent_2.wav"], cfg_scale=1.5)
174
+ wav, sr = tts.tts("Muraho neza.", voice="agent_1.wav")
175
+ tts.enroll_speaker("agent_claire", ["claire_1.wav", "claire_2.wav"], gender="female")
176
+ wav, sr = tts.tts("Murakoze guhamagara.", voice="agent_claire", emotion="calm", intensity=0.4)
177
+
178
+ # H. Fastest CPU synthesis
179
+ wav, sr = tts.tts("Muraho neza.", voice="female", steps=1)
180
+
181
+ # I. Explain how a text will be read (QA before shipping prompts)
182
+ print(tts.analyze("Konti 0788123456 ifite FRW 2,500. <en>Thank you.</en>")["plan"])
183
+ ```
184
+
185
+ Command line equivalents: `altatts synthesize --model runs/kin_v2 --text "..." --voice female --emotion calm --intensity 0.5 --steps 8 --seed 1 --sample-rate 8000 --out p.wav`, `--list-voices`, `--capabilities`, `--explain`, `--reference clip.wav`.
186
+
187
+ ## 4. Voices: production, enrolled, cloned
188
+
189
+ A trained ALTATTS 2 model ships **anonymized production voices**, grouped by language family, each a verified mixture of training speakers that matches none of them:
190
+
191
+ | group | languages | voices |
192
+ |---|---|---|
193
+ | `bantu` | Kinyarwanda, Swahili, code-switching | `bantu_female_1`, `bantu_female_2`, `bantu_male_1`, `bantu_male_2` |
194
+ | `french` | French | `french_female_1/2`, `french_male_1/2` |
195
+ | `english` | English | `english_female_1/2`, `english_male_1/2` |
196
+
197
+ Aliases: `female` / `male` (primary language group), `fr_female`, `fra_male`, `rw_female`, `kin_male`, `sw_female`, `en_male`, `bantu_female`, … A single-language model gets one group with three voices per gender (`female_young`, `female_adult`, `female_senior`, …). `privacy_report.json` records the similarity every voice achieved.
198
+
199
+ ```bash
200
+ altatts voices list --model runs/kin_v2
201
+ altatts-enroll --model runs/kin_v2 --name agent_claire --audio c1.wav c2.wav --gender female
202
+ altatts-enroll --model runs/kin_v2 --name agent_claire --audio c1.wav --text "Muraho neza." --adapt-steps 300
203
+ ```
204
+
205
+ Enrollment tips: 10–30 s of clean speech, several clips, the same microphone as production; `cfg_scale` 1.3–1.8 strengthens the identity; `--adapt-steps` (few-shot) when the model saw few training speakers.
206
+
207
+ ## 5. Live streaming
208
+
209
+ ```python
210
+ from altatts import Synthesizer, StreamingSynthesizer
211
+
212
+ tts = Synthesizer.from_pretrained("runs/kin_v2")
213
+ stream = StreamingSynthesizer(tts, voice="female", sample_rate=8000,
214
+ emotion="calm", intensity=0.5, steps=2) # live settings
215
+
216
+ # known text: audio starts after the FIRST sentence
217
+ for chunk in stream.stream("Muraho. [pause:0.3] Turabafasha gute uyu munsi?"):
218
+ send_to_caller(chunk) # float32; exact pauses arrive as silent chunks
219
+
220
+ # LLM token stream: speak each sentence as soon as it completes
221
+ for token in llm_tokens:
222
+ for chunk in stream.feed(token):
223
+ send_to_caller(chunk)
224
+ for chunk in stream.flush():
225
+ send_to_caller(chunk)
226
+ print(stream.first_chunk_latency_s)
227
+ stream.reset(voice="male", emotion="happy")
228
+ ```
229
+
230
+ Best live settings: `steps=2` (GPU) or `steps=1` (CPU), `noise_scale=0.667`, `sample_rate=8000` for telephony / `16000` for voice bots, `min_chars=6` (default) so very short fragments wait for the next sentence. Pass `reference_audio=` once to the constructor to stream in a cloned voice. Telephony framing: `altatts.integrations.callcenter.streaming_telephony_frames`.
231
+
232
+ ## 6. Serve it as an API and deploy with one command
233
+
234
+ ```bash
235
+ altatts serve --model runs/kin_v2 --port 8081 # REST + WebSocket, no extra packages
236
+ ```
237
+
238
+ | endpoint | purpose |
239
+ |---|---|
240
+ | `GET /health`, `/capabilities`, `/voices` | status, what the model can do, voice list |
241
+ | `GET /tts?text=…&voice=…` | quick test → WAV |
242
+ | `POST /tts` | JSON request → `wav` / `pcm16` / `mulaw` / `alaw` bytes, or `format: "json"` (base64) |
243
+ | `POST /tts/stream` | chunked audio, one chunk per phrase (first bytes after the first sentence) |
244
+ | `WS /ws` | live streaming: send `{"text": …}` or `{"reset": …}` + `{"feed": "token"}` … `{"flush": true}`; receive binary chunks |
245
+ | `POST /voices/enroll`, `DELETE /voices/<name>` | add / remove voices at runtime (`--no-enroll` to lock) |
246
+ | `POST /analyze` | normalization + synthesis plan for QA |
247
+
248
+ Request fields = the Python parameters (`text, voice, emotion, intensity, language, sample_rate, format, speed, noise_scale, steps, cfg_scale, seed, pause_scale, reference`).
249
+
250
+ ```bash
251
+ curl -s localhost:8081/tts -H 'Content-Type: application/json' -d '{
252
+ "text": "Murakaza neza. [pause:0.4] Twishimiye kubafasha!",
253
+ "voice": "bantu_female_1", "emotion": "calm", "intensity": 0.5,
254
+ "sample_rate": 8000, "format": "mulaw", "seed": 1 }' -o prompt.ulaw
255
+ curl -sN localhost:8081/tts/stream -H 'Content-Type: application/json' \
256
+ -d '{"text": "Muraho. Amakuru yawe?", "voice": "female", "sample_rate": 16000}' > live.pcm
257
+ ```
258
+
259
+ ```python
260
+ from altatts.client import TTSClient # standard library client
261
+ api = TTSClient("http://tts.internal:8081")
262
+ wav, sr = api.tts("Muraho neza.", voice="female", emotion="calm")
263
+ for chunk in api.stream("Muraho. Amakuru?", sample_rate=8000, format="mulaw"):
264
+ rtp_send(chunk)
265
+ api.enroll("agent_claire", ["c1.wav", "c2.wav"], gender="female")
266
+ ```
267
+
268
+ **Deploy on a server** (model + Dockerfile + compose + README generated for you):
269
+
270
+ ```bash
271
+ altatts package --model runs/kin_v2 --out deploy/altatts-api # add --gpu for a CUDA image
272
+ scp -r deploy/altatts-api server:/srv/ && ssh server 'cd /srv/altatts-api && docker compose up -d'
273
+ curl -s server:8081/health
274
+ ```
275
+
276
+ Enrolled voices persist (`voices.json` is mounted from the host). Put the service behind your reverse proxy / auth; run one instance per GPU or CPU socket and load-balance for throughput.
277
+
278
+ ## 7. Call centers
279
+
280
+ ```python
281
+ from altatts.integrations.callcenter import (telephony_frames, streaming_telephony_frames,
282
+ twilio_media_messages, VoiceAgent,
283
+ prerender_prompts, enroll_agent)
284
+ for frame in telephony_frames(tts, "Murakoze guhamagara.", voice="female", emotion="calm"):
285
+ rtp_send(frame) # 160-byte G.711 frames
286
+ agent = VoiceAgent(asr, tts, respond_fn=my_bot, voice="agent_eric", emotion="calm", steps=2)
287
+ prerender_prompts(tts, {"welcome": "Murakaza neza.", "menu": "Kanda rimwe ..."},
288
+ out_dir="ivr/", voice="bantu_female_1", emotion="calm", seed=1)
289
+ ```
290
+
291
+ ## 8. Train on your data
292
+
293
+ Any corpus shape works: plain ASR data, or data with speaker / gender / age / language / emotion / intensity / pause annotations, monolingual or code-switched, in any mix (details and every field in `docs/DATASET.md`).
294
+
295
+ ```bash
296
+ altatts-prepare-data --metadata fr.jsonl en.jsonl rw.jsonl sw.jsonl cs.jsonl --audio-root /data \
297
+ --out /data/tts/train.jsonl --languages rw en fr sw --auto-pauses punct --convert-audio flac
298
+ altatts-train --recipe multilingual_callcenter --gpus all \
299
+ --train-metadata /data/tts/train_converted.jsonl --val-metadata /data/tts/val_converted.jsonl \
300
+ --audio-root /data/tts/audio_flac --out runs/kin_v2
301
+ altatts-evaluate --model runs/kin_v2 --metadata test.jsonl --audio-root /data \
302
+ --asr-model /path/altasr --target-wer 0.01 --robustness --clone
303
+ ```
304
+
305
+ Training ends with the 12 production voices built and verified; `altatts recipes` lists the shipped configs; `--init-from` fine-tunes or upgrades an existing model; `--nodes` trains across machines. Every run writes `logs/train.log`, `metrics.jsonl`, `history.jsonl` and a live `status.json` (plus TensorBoard / W&B when installed), prints the validation error per corpus each epoch, and `--early-stop-patience N` stops when `val_mel_l1` stops improving; `altatts logs --run runs/x` summarises a run.
306
+
307
+ ## 9. Troubleshooting
308
+
309
+ - Anything environment-related: `altatts doctor` → `altatts doctor --fix`.
310
+ - `voice cloning needs an ALTATTS 2 model`: a 0.1 folder; upgrade with `--init-from`.
311
+ - Emotion has no audible effect: not in the training labels; label a subset and fine-tune; raise `intensity`/`cfg_scale`.
312
+ - A production voice is flagged in `privacy_report.json`: rebuild with `altatts voices build --seed N` or add speakers of that gender/family.
313
+ - Slow on CPU: `steps=1`, `--preset small`, pre-render fixed prompts, or deploy the API on a GPU box.
314
+
315
+ Full manual: `docs/USAGE.md`. Dataset guide: `docs/DATASET.md`. Apache-2.0 · YaliLabs / ALTA Project
@@ -0,0 +1,268 @@
1
+ # ALTATTS
2
+
3
+ **Natural, expressive, multilingual text-to-speech with zero-shot voice cloning. Built for Kinyarwanda; speaks English, French and Swahili too; ready for call centers; one command to serve as an API.**
4
+
5
+ ALTATTS is the speaking half of the ALTA stack: [ALTASR](https://pypi.org/project/altasr/) listens, ALTATTS talks.
6
+
7
+ | capability | how |
8
+ |---|---|
9
+ | Natural prosody | **MeanFlow latent prior** (Geng, Deng, Bai, Kolter & He, 2025): the whole utterance is generated jointly in 1–4 steps |
10
+ | Word-exact speech | deterministic durations + monotonic alignment: no skipped or repeated words |
11
+ | Emotion and intensity | `emotion="happy", intensity=0.7` or inline `[calm]`, `[excited:0.8]` |
12
+ | Human behaviour | exact `[pause:0.5]`, natural `[pause]`, `[laugh]`, `[breath]`, `[sigh]`, hesitations |
13
+ | Voice cloning | enroll a speaker from a few seconds of audio, use it immediately, no training |
14
+ | Privacy | 12 anonymized **production voices** (French, English, Bantu groups: 2 F + 2 M each) that match no training speaker |
15
+ | Code-switching | Kinyarwanda, English, French, Swahili in one model, word-level language detection, per-language number reading |
16
+ | Telephony | 8 kHz G.711 μ-law / A-law, 20 ms frames, Twilio messages, phrase streaming |
17
+ | Serving | `altatts serve` (REST + WebSocket, standard library only) and `altatts package` (Docker folder, `docker compose up`) |
18
+ | Anywhere | CPU, one GPU, all GPUs, several machines; `altatts doctor --fix` repairs PyTorch/CUDA/audio installs |
19
+
20
+ Every ALTATTS 0.1 interface still works and 0.1 checkpoints load unchanged.
21
+
22
+ ---
23
+
24
+ ## 1. Install and check
25
+
26
+ ```bash
27
+ pip install "altatts[av]" # av = mp3/webm/opus decoding; "altatts[all]" for everything
28
+ altatts doctor # Python / torch / CUDA / audio deps -> PASS/WARN/FAIL + fixes
29
+ altatts doctor --fix # repair what is safe (matched torch for your driver, missing deps)
30
+ ```
31
+
32
+ A plain `pip install torch` pulls the newest CUDA build (cu130 today), which
33
+ does not run on older drivers (a 570.x driver supports CUDA ≤ 12.8).
34
+ `altatts doctor --fix` cross-checks the driver's ceiling, the GPU's
35
+ compute-capability floor and the wheels actually published for your Python
36
+ and CPU architecture, prints the choice, installs the newest torch the
37
+ machine can run (exact pins, right index), re-verifies CUDA and rolls back
38
+ on failure. `--fix --dry-run` shows the cross-check without changing
39
+ anything; `--index-url cu126` forces an index. The manual equivalent:
40
+
41
+ ```bash
42
+ pip install --force-reinstall "torch==2.14.1+cu126" torchaudio --index-url https://download.pytorch.org/whl/cu126
43
+ python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
44
+ ```
45
+
46
+ ## 2. Which model do I have? ("generation")
47
+
48
+ A model folder's `config.json` carries `"model": {"version": N}`. This is only a **generation number**, never something you set by hand:
49
+
50
+ | generation | what it means | cloning / emotions / MeanFlow |
51
+ |---|---|---|
52
+ | **ALTATTS 2** (`version: 2`) | trained with altatts ≥ 2.0 | yes |
53
+ | **ALTATTS 0.1 (legacy)** (no `version` key) | trained with altatts 0.1, plain VITS | no, but every 0.1 call still works |
54
+
55
+ ```python
56
+ tts.capabilities()["generation"] # 'ALTATTS 2' or 'ALTATTS 0.1 (legacy VITS)'
57
+ ```
58
+
59
+ Upgrade a 0.1 model by fine-tuning: `altatts-train --init-from runs/old_model --preset base ...` (all VITS weights are reused).
60
+
61
+ ## 3. Synthesize
62
+
63
+ ```python
64
+ from altatts import Synthesizer
65
+
66
+ tts = Synthesizer.from_pretrained("runs/kin_v2")
67
+ wav, sr = tts.tts("Muraho! Amakuru yawe?", voice="female") # the 0.1 call
68
+ tts.tts_to_file("Murakaza neza.", "hello.wav", voice="male", sample_rate=8000)
69
+ print(tts.voices()) # production voices, enrolled voices, aliases
70
+ print(tts.capabilities()) # generation, emotions, languages, cloning, pause token ...
71
+ ```
72
+
73
+ ### Every control, and the value that works best
74
+
75
+ | parameter | values | best practice |
76
+ |---|---|---|
77
+ | `voice` | `female`, `male`, `bantu_female_1`, `french_male_2`, `english_female_1`, `fr_female`, `kin_male`, an enrolled name, a training speaker, **or a path to a reference clip** | pick the group that matches the sentence language; `female`/`male` are the primary-language voices |
78
+ | `emotion` | `neutral happy sad angry fearful surprised disgusted calm excited` | `calm` for service lines, `happy` for greetings; only emotions seen in training have an effect (`capabilities()["emotions_seen_in_training"]`) |
79
+ | `intensity` | 0–1 | 0.3 subtle, **0.6 natural**, 1.0 strong |
80
+ | `speed` | 0.5–2 | **1.0**; 0.95 for instructions/health lines, 1.05–1.1 for busy IVR menus |
81
+ | `noise_scale` | 0–1 | **0.667** (standard); 0.5 for maximally consistent prompts, 0.8 for lively narration |
82
+ | `steps` | 1–8 | **4** default; 1 = fastest (CPU/live), 8 = maximum naturalness for pre-rendered media |
83
+ | `cfg_scale` | 1–2 | **1.0**; 1.3–1.8 amplifies a cloned identity or an emotion |
84
+ | `seed` | int | set it for reproducible prompts (same text → same audio) |
85
+ | `sample_rate` | 8000 … 48000 | 8000 telephony, 16000 ASR/voice bots, 22050 native, 48000 media |
86
+ | `language` | `rw en fr sw` (`kin eng fra swa` accepted) | set it for a monolingual non-primary sentence; mixed text is detected word by word; force spans with `<en>…</en>` |
87
+ | `pause_scale` | float | multiplies every `[pause:x]` |
88
+ | `reference_audio` (+ `reference_sr` for arrays) | path, array, `(array, sr)` or a list of clips | one-off cloning from a clip; 10–30 s of clean speech works best |
89
+ | `speaker_embedding` | vector from `tts.embed_speaker(...)` | fastest repeated cloning (embed once, reuse) |
90
+ | `prior` | `meanflow` / `flow` | `flow` = the 0.1 sampler, only for A/B comparisons |
91
+
92
+ ### Scenarios with their best configurations
93
+
94
+ ```python
95
+ # A. Call-center / IVR prompts (pre-rendered, 8 kHz, identical every time)
96
+ wav, sr = tts.tts("Murakaza neza kuri banki yacu. [pause:0.4] Kanda rimwe ku konti yawe.",
97
+ voice="bantu_female_1", emotion="calm", intensity=0.5,
98
+ speed=0.97, noise_scale=0.5, steps=8, seed=1, sample_rate=8000)
99
+ ulaw = tts.mulaw_bytes("Murakoze guhamagara.", voice="female", emotion="calm", seed=1)
100
+
101
+ # B. Live voice agent (lowest latency; stream phrase by phrase, see §5)
102
+ wav, sr = tts.tts("Yego, ndabikora nonaha.", voice="female", steps=2, sample_rate=16000)
103
+
104
+ # C. Media / audiobook narration (maximum naturalness)
105
+ wav, sr = tts.tts("Umwana yarahagurutse, [breath] areba hirya no hino, [pause:0.8] "
106
+ "maze aratangira kwiruka.", voice="bantu_male_2", emotion="excited",
107
+ intensity=0.6, noise_scale=0.8, steps=8, sample_rate=48000)
108
+
109
+ # D. Emotion sweep (faint -> ecstatic) on the same sentence
110
+ for inten in (0.2, 0.5, 0.8, 1.0):
111
+ wav, sr = tts.tts("Twishimiye cyane kubabona!", voice="female",
112
+ emotion="happy", intensity=inten, cfg_scale=1.3, seed=3)
113
+
114
+ # E. Code-switching and numbers (read in each sentence's language)
115
+ wav, sr = tts.tts("Konti yawe ifite FRW 2,500. <en>Your balance is 2,500 francs.</en> "
116
+ "Votre solde est de 2500 FRW. Salio lako ni FRW 2500.",
117
+ voice="bantu_female_2", steps=4)
118
+ wav, sr = tts.tts("Bonjour, votre dossier est prêt.", voice="french_female_1", language="fr")
119
+ wav, sr = tts.tts("Habari, akaunti yako iko tayari.", voice="bantu_male_1", language="sw")
120
+
121
+ # F. Human behaviour tags
122
+ wav, sr = tts.tts("Hmm [hesitation] ndabona. [pause:0.6] [laugh] Nibyo rwose! [breath] Reka nkwereke.",
123
+ voice="male", emotion="happy", intensity=0.5)
124
+
125
+ # G. Cloning: one-off, by path, enrolled
126
+ wav, sr = tts.tts("Muraho neza.", reference_audio=["agent_1.wav", "agent_2.wav"], cfg_scale=1.5)
127
+ wav, sr = tts.tts("Muraho neza.", voice="agent_1.wav")
128
+ tts.enroll_speaker("agent_claire", ["claire_1.wav", "claire_2.wav"], gender="female")
129
+ wav, sr = tts.tts("Murakoze guhamagara.", voice="agent_claire", emotion="calm", intensity=0.4)
130
+
131
+ # H. Fastest CPU synthesis
132
+ wav, sr = tts.tts("Muraho neza.", voice="female", steps=1)
133
+
134
+ # I. Explain how a text will be read (QA before shipping prompts)
135
+ print(tts.analyze("Konti 0788123456 ifite FRW 2,500. <en>Thank you.</en>")["plan"])
136
+ ```
137
+
138
+ Command line equivalents: `altatts synthesize --model runs/kin_v2 --text "..." --voice female --emotion calm --intensity 0.5 --steps 8 --seed 1 --sample-rate 8000 --out p.wav`, `--list-voices`, `--capabilities`, `--explain`, `--reference clip.wav`.
139
+
140
+ ## 4. Voices: production, enrolled, cloned
141
+
142
+ A trained ALTATTS 2 model ships **anonymized production voices**, grouped by language family, each a verified mixture of training speakers that matches none of them:
143
+
144
+ | group | languages | voices |
145
+ |---|---|---|
146
+ | `bantu` | Kinyarwanda, Swahili, code-switching | `bantu_female_1`, `bantu_female_2`, `bantu_male_1`, `bantu_male_2` |
147
+ | `french` | French | `french_female_1/2`, `french_male_1/2` |
148
+ | `english` | English | `english_female_1/2`, `english_male_1/2` |
149
+
150
+ Aliases: `female` / `male` (primary language group), `fr_female`, `fra_male`, `rw_female`, `kin_male`, `sw_female`, `en_male`, `bantu_female`, … A single-language model gets one group with three voices per gender (`female_young`, `female_adult`, `female_senior`, …). `privacy_report.json` records the similarity every voice achieved.
151
+
152
+ ```bash
153
+ altatts voices list --model runs/kin_v2
154
+ altatts-enroll --model runs/kin_v2 --name agent_claire --audio c1.wav c2.wav --gender female
155
+ altatts-enroll --model runs/kin_v2 --name agent_claire --audio c1.wav --text "Muraho neza." --adapt-steps 300
156
+ ```
157
+
158
+ Enrollment tips: 10–30 s of clean speech, several clips, the same microphone as production; `cfg_scale` 1.3–1.8 strengthens the identity; `--adapt-steps` (few-shot) when the model saw few training speakers.
159
+
160
+ ## 5. Live streaming
161
+
162
+ ```python
163
+ from altatts import Synthesizer, StreamingSynthesizer
164
+
165
+ tts = Synthesizer.from_pretrained("runs/kin_v2")
166
+ stream = StreamingSynthesizer(tts, voice="female", sample_rate=8000,
167
+ emotion="calm", intensity=0.5, steps=2) # live settings
168
+
169
+ # known text: audio starts after the FIRST sentence
170
+ for chunk in stream.stream("Muraho. [pause:0.3] Turabafasha gute uyu munsi?"):
171
+ send_to_caller(chunk) # float32; exact pauses arrive as silent chunks
172
+
173
+ # LLM token stream: speak each sentence as soon as it completes
174
+ for token in llm_tokens:
175
+ for chunk in stream.feed(token):
176
+ send_to_caller(chunk)
177
+ for chunk in stream.flush():
178
+ send_to_caller(chunk)
179
+ print(stream.first_chunk_latency_s)
180
+ stream.reset(voice="male", emotion="happy")
181
+ ```
182
+
183
+ Best live settings: `steps=2` (GPU) or `steps=1` (CPU), `noise_scale=0.667`, `sample_rate=8000` for telephony / `16000` for voice bots, `min_chars=6` (default) so very short fragments wait for the next sentence. Pass `reference_audio=` once to the constructor to stream in a cloned voice. Telephony framing: `altatts.integrations.callcenter.streaming_telephony_frames`.
184
+
185
+ ## 6. Serve it as an API and deploy with one command
186
+
187
+ ```bash
188
+ altatts serve --model runs/kin_v2 --port 8081 # REST + WebSocket, no extra packages
189
+ ```
190
+
191
+ | endpoint | purpose |
192
+ |---|---|
193
+ | `GET /health`, `/capabilities`, `/voices` | status, what the model can do, voice list |
194
+ | `GET /tts?text=…&voice=…` | quick test → WAV |
195
+ | `POST /tts` | JSON request → `wav` / `pcm16` / `mulaw` / `alaw` bytes, or `format: "json"` (base64) |
196
+ | `POST /tts/stream` | chunked audio, one chunk per phrase (first bytes after the first sentence) |
197
+ | `WS /ws` | live streaming: send `{"text": …}` or `{"reset": …}` + `{"feed": "token"}` … `{"flush": true}`; receive binary chunks |
198
+ | `POST /voices/enroll`, `DELETE /voices/<name>` | add / remove voices at runtime (`--no-enroll` to lock) |
199
+ | `POST /analyze` | normalization + synthesis plan for QA |
200
+
201
+ Request fields = the Python parameters (`text, voice, emotion, intensity, language, sample_rate, format, speed, noise_scale, steps, cfg_scale, seed, pause_scale, reference`).
202
+
203
+ ```bash
204
+ curl -s localhost:8081/tts -H 'Content-Type: application/json' -d '{
205
+ "text": "Murakaza neza. [pause:0.4] Twishimiye kubafasha!",
206
+ "voice": "bantu_female_1", "emotion": "calm", "intensity": 0.5,
207
+ "sample_rate": 8000, "format": "mulaw", "seed": 1 }' -o prompt.ulaw
208
+ curl -sN localhost:8081/tts/stream -H 'Content-Type: application/json' \
209
+ -d '{"text": "Muraho. Amakuru yawe?", "voice": "female", "sample_rate": 16000}' > live.pcm
210
+ ```
211
+
212
+ ```python
213
+ from altatts.client import TTSClient # standard library client
214
+ api = TTSClient("http://tts.internal:8081")
215
+ wav, sr = api.tts("Muraho neza.", voice="female", emotion="calm")
216
+ for chunk in api.stream("Muraho. Amakuru?", sample_rate=8000, format="mulaw"):
217
+ rtp_send(chunk)
218
+ api.enroll("agent_claire", ["c1.wav", "c2.wav"], gender="female")
219
+ ```
220
+
221
+ **Deploy on a server** (model + Dockerfile + compose + README generated for you):
222
+
223
+ ```bash
224
+ altatts package --model runs/kin_v2 --out deploy/altatts-api # add --gpu for a CUDA image
225
+ scp -r deploy/altatts-api server:/srv/ && ssh server 'cd /srv/altatts-api && docker compose up -d'
226
+ curl -s server:8081/health
227
+ ```
228
+
229
+ Enrolled voices persist (`voices.json` is mounted from the host). Put the service behind your reverse proxy / auth; run one instance per GPU or CPU socket and load-balance for throughput.
230
+
231
+ ## 7. Call centers
232
+
233
+ ```python
234
+ from altatts.integrations.callcenter import (telephony_frames, streaming_telephony_frames,
235
+ twilio_media_messages, VoiceAgent,
236
+ prerender_prompts, enroll_agent)
237
+ for frame in telephony_frames(tts, "Murakoze guhamagara.", voice="female", emotion="calm"):
238
+ rtp_send(frame) # 160-byte G.711 frames
239
+ agent = VoiceAgent(asr, tts, respond_fn=my_bot, voice="agent_eric", emotion="calm", steps=2)
240
+ prerender_prompts(tts, {"welcome": "Murakaza neza.", "menu": "Kanda rimwe ..."},
241
+ out_dir="ivr/", voice="bantu_female_1", emotion="calm", seed=1)
242
+ ```
243
+
244
+ ## 8. Train on your data
245
+
246
+ Any corpus shape works: plain ASR data, or data with speaker / gender / age / language / emotion / intensity / pause annotations, monolingual or code-switched, in any mix (details and every field in `docs/DATASET.md`).
247
+
248
+ ```bash
249
+ altatts-prepare-data --metadata fr.jsonl en.jsonl rw.jsonl sw.jsonl cs.jsonl --audio-root /data \
250
+ --out /data/tts/train.jsonl --languages rw en fr sw --auto-pauses punct --convert-audio flac
251
+ altatts-train --recipe multilingual_callcenter --gpus all \
252
+ --train-metadata /data/tts/train_converted.jsonl --val-metadata /data/tts/val_converted.jsonl \
253
+ --audio-root /data/tts/audio_flac --out runs/kin_v2
254
+ altatts-evaluate --model runs/kin_v2 --metadata test.jsonl --audio-root /data \
255
+ --asr-model /path/altasr --target-wer 0.01 --robustness --clone
256
+ ```
257
+
258
+ Training ends with the 12 production voices built and verified; `altatts recipes` lists the shipped configs; `--init-from` fine-tunes or upgrades an existing model; `--nodes` trains across machines. Every run writes `logs/train.log`, `metrics.jsonl`, `history.jsonl` and a live `status.json` (plus TensorBoard / W&B when installed), prints the validation error per corpus each epoch, and `--early-stop-patience N` stops when `val_mel_l1` stops improving; `altatts logs --run runs/x` summarises a run.
259
+
260
+ ## 9. Troubleshooting
261
+
262
+ - Anything environment-related: `altatts doctor` → `altatts doctor --fix`.
263
+ - `voice cloning needs an ALTATTS 2 model`: a 0.1 folder; upgrade with `--init-from`.
264
+ - Emotion has no audible effect: not in the training labels; label a subset and fine-tune; raise `intensity`/`cfg_scale`.
265
+ - A production voice is flagged in `privacy_report.json`: rebuild with `altatts voices build --seed N` or add speakers of that gender/family.
266
+ - Slow on CPU: `steps=1`, `--preset small`, pre-render fixed prompts, or deploy the API on a GPU box.
267
+
268
+ Full manual: `docs/USAGE.md`. Dataset guide: `docs/DATASET.md`. Apache-2.0 · YaliLabs / ALTA Project