altatts 2.1.0__tar.gz → 2.2__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 (234) hide show
  1. altatts-2.2/PKG-INFO +388 -0
  2. altatts-2.2/PYPI_README.md +326 -0
  3. altatts-2.2/README.md +426 -0
  4. {altatts-2.1.0 → altatts-2.2}/altatts/__init__.py +15 -2
  5. {altatts-2.1.0 → altatts-2.2}/altatts/audio.py +158 -33
  6. altatts-2.2/altatts/benchmark.py +443 -0
  7. altatts-2.2/altatts/client.py +165 -0
  8. altatts-2.2/altatts/config.py +1315 -0
  9. altatts-2.2/altatts/datasets/__init__.py +36 -0
  10. {altatts-2.1.0 → altatts-2.2}/altatts/datasets/adapters.py +207 -24
  11. altatts-2.2/altatts/datasets/asraudit.py +538 -0
  12. altatts-2.2/altatts/datasets/audioqa.py +470 -0
  13. altatts-2.2/altatts/datasets/cli.py +131 -0
  14. {altatts-2.1.0 → altatts-2.2}/altatts/datasets/combine.py +60 -11
  15. altatts-2.2/altatts/datasets/combine_v3.py +841 -0
  16. altatts-2.2/altatts/datasets/dedup.py +205 -0
  17. altatts-2.2/altatts/datasets/emotions.py +461 -0
  18. altatts-2.2/altatts/datasets/mispair.py +243 -0
  19. {altatts-2.1.0 → altatts-2.2}/altatts/datasets/registry.py +97 -3
  20. altatts-2.2/altatts/datasets/speakers.py +546 -0
  21. {altatts-2.1.0 → altatts-2.2}/altatts/datasets/spec.py +6 -0
  22. altatts-2.2/altatts/datasets/textqa.py +752 -0
  23. altatts-2.2/altatts/datasets/validate.py +867 -0
  24. altatts-2.2/altatts/deploy.py +509 -0
  25. {altatts-2.1.0 → altatts-2.2}/altatts/env/checks.py +237 -13
  26. {altatts-2.1.0 → altatts-2.2}/altatts/env/compat.py +10 -0
  27. {altatts-2.1.0 → altatts-2.2}/altatts/env/doctor.py +2 -1
  28. altatts-2.2/altatts/export.py +553 -0
  29. altatts-2.2/altatts/inference/checkpoint.py +318 -0
  30. altatts-2.2/altatts/inference/cloning_eval.py +1385 -0
  31. altatts-2.2/altatts/inference/evaluate.py +1405 -0
  32. altatts-2.2/altatts/inference/staged.py +602 -0
  33. altatts-2.2/altatts/inference/streaming.py +459 -0
  34. {altatts-2.1.0 → altatts-2.2}/altatts/inference/synthesize.py +56 -2
  35. altatts-2.2/altatts/inference/synthesizer.py +960 -0
  36. altatts-2.2/altatts/inference/voices.py +273 -0
  37. {altatts-2.1.0 → altatts-2.2}/altatts/integrations/callcenter.py +50 -11
  38. altatts-2.2/altatts/languages/__init__.py +726 -0
  39. altatts-2.2/altatts/languages/data/NOTICE +21 -0
  40. altatts-2.2/altatts/languages/data/rw_acronyms_loans.tsv +271 -0
  41. altatts-2.2/altatts/languages/data/rw_common.txt +1644 -0
  42. altatts-2.2/altatts/languages/data/rw_names_places.tsv +1065 -0
  43. altatts-2.2/altatts/languages/english.py +182 -0
  44. altatts-2.2/altatts/languages/french.py +178 -0
  45. altatts-2.2/altatts/languages/kinyarwanda.py +630 -0
  46. altatts-2.2/altatts/languages/swahili.py +177 -0
  47. altatts-2.2/altatts/lexicon.py +1047 -0
  48. {altatts-2.1.0 → altatts-2.2}/altatts/main_cli.py +11 -0
  49. altatts-2.2/altatts/metrics.py +1001 -0
  50. altatts-2.2/altatts/model/__init__.py +30 -0
  51. altatts-2.2/altatts/model/adversarial.py +87 -0
  52. {altatts-2.1.0 → altatts-2.2}/altatts/model/latent.py +25 -3
  53. altatts-2.2/altatts/model/losses.py +291 -0
  54. altatts-2.2/altatts/model/mas_triton.py +117 -0
  55. altatts-2.2/altatts/model/meanflow.py +648 -0
  56. {altatts-2.1.0 → altatts-2.2}/altatts/model/modules.py +23 -7
  57. altatts-2.2/altatts/model/monotonic_align.py +414 -0
  58. altatts-2.2/altatts/model/style.py +304 -0
  59. {altatts-2.1.0 → altatts-2.2}/altatts/model/text_encoder.py +19 -4
  60. altatts-2.2/altatts/model/variance.py +359 -0
  61. altatts-2.2/altatts/model/vits.py +1143 -0
  62. {altatts-2.1.0 → altatts-2.2}/altatts/model/waveform.py +157 -6
  63. altatts-2.2/altatts/phonemes.py +345 -0
  64. altatts-2.2/altatts/prosody.py +377 -0
  65. altatts-2.2/altatts/recipes/callcenter_robust.json +430 -0
  66. {altatts-2.1.0 → altatts-2.2}/altatts/recipes/multilingual_callcenter.json +81 -12
  67. altatts-2.2/altatts/serving.py +1555 -0
  68. altatts-2.2/altatts/speaker/__init__.py +9 -0
  69. altatts-2.2/altatts/speaker/checks.py +52 -0
  70. altatts-2.2/altatts/speaker/encoders.py +1257 -0
  71. altatts-2.2/altatts/speaker/enroll.py +897 -0
  72. {altatts-2.1.0 → altatts-2.2}/altatts/speaker/enroll_cli.py +36 -3
  73. altatts-2.2/altatts/speaker/similarity.py +146 -0
  74. {altatts-2.1.0 → altatts-2.2}/altatts/tags.py +156 -10
  75. altatts-2.2/altatts/text.py +1275 -0
  76. altatts-2.2/altatts/training/anonymize.py +1461 -0
  77. altatts-2.2/altatts/training/compare.py +178 -0
  78. altatts-2.2/altatts/training/data.py +1939 -0
  79. {altatts-2.1.0 → altatts-2.2}/altatts/training/ema.py +9 -1
  80. altatts-2.2/altatts/training/evalset.py +167 -0
  81. altatts-2.2/altatts/training/guard.py +546 -0
  82. {altatts-2.1.0 → altatts-2.2}/altatts/training/launch.py +73 -1
  83. altatts-2.2/altatts/training/logging.py +955 -0
  84. altatts-2.2/altatts/training/pace.py +116 -0
  85. {altatts-2.1.0 → altatts-2.2}/altatts/training/prepare.py +44 -16
  86. altatts-2.2/altatts/training/selection.py +848 -0
  87. altatts-2.2/altatts/training/train.py +953 -0
  88. altatts-2.2/altatts/training/trainer.py +4747 -0
  89. {altatts-2.1.0 → altatts-2.2}/altatts/utils.py +119 -15
  90. {altatts-2.1.0 → altatts-2.2}/altatts/voices_cli.py +28 -1
  91. altatts-2.2/altatts.egg-info/PKG-INFO +388 -0
  92. altatts-2.2/altatts.egg-info/SOURCES.txt +190 -0
  93. {altatts-2.1.0 → altatts-2.2}/altatts.egg-info/requires.txt +18 -0
  94. {altatts-2.1.0 → altatts-2.2}/pyproject.toml +16 -6
  95. altatts-2.2/tests/test_asraudit.py +319 -0
  96. altatts-2.2/tests/test_audioqa.py +254 -0
  97. altatts-2.2/tests/test_callcenter_robust.py +261 -0
  98. altatts-2.2/tests/test_checkpoint_loading.py +135 -0
  99. altatts-2.2/tests/test_clean_console.py +101 -0
  100. altatts-2.2/tests/test_cloning_adapt.py +125 -0
  101. altatts-2.2/tests/test_cloning_eval.py +458 -0
  102. altatts-2.2/tests/test_cloning_gates.py +207 -0
  103. altatts-2.2/tests/test_cloning_vectors.py +171 -0
  104. altatts-2.2/tests/test_combine_v3.py +227 -0
  105. {altatts-2.1.0 → altatts-2.2}/tests/test_config_and_data.py +88 -0
  106. altatts-2.2/tests/test_config_validation.py +177 -0
  107. altatts-2.2/tests/test_data_emotions.py +358 -0
  108. altatts-2.2/tests/test_data_speaker_cache.py +339 -0
  109. altatts-2.2/tests/test_data_style_gates.py +302 -0
  110. altatts-2.2/tests/test_datasets_v3_sources.py +374 -0
  111. altatts-2.2/tests/test_deploy.py +162 -0
  112. altatts-2.2/tests/test_detect_genders_conflict.py +60 -0
  113. altatts-2.2/tests/test_discriminators.py +200 -0
  114. altatts-2.2/tests/test_doctor_checkpoint.py +53 -0
  115. altatts-2.2/tests/test_dtw_vectorised.py +109 -0
  116. altatts-2.2/tests/test_evalset.py +178 -0
  117. altatts-2.2/tests/test_evaluate_protocol.py +428 -0
  118. altatts-2.2/tests/test_export_static.py +107 -0
  119. altatts-2.2/tests/test_fleurs_tsv_twice.py +73 -0
  120. altatts-2.2/tests/test_g711.py +182 -0
  121. altatts-2.2/tests/test_gan_balance.py +246 -0
  122. altatts-2.2/tests/test_guard.py +320 -0
  123. altatts-2.2/tests/test_handoff_integration.py +440 -0
  124. altatts-2.2/tests/test_inference_gates.py +599 -0
  125. altatts-2.2/tests/test_last_error.py +33 -0
  126. altatts-2.2/tests/test_loader_knobs.py +341 -0
  127. altatts-2.2/tests/test_log_rendering.py +235 -0
  128. {altatts-2.1.0 → altatts-2.2}/tests/test_logging_early_stop.py +51 -22
  129. altatts-2.2/tests/test_mas.py +406 -0
  130. altatts-2.2/tests/test_metrics_values.py +231 -0
  131. altatts-2.2/tests/test_mispair.py +78 -0
  132. {altatts-2.1.0 → altatts-2.2}/tests/test_model.py +22 -1
  133. altatts-2.2/tests/test_model_audit_fixes.py +1023 -0
  134. altatts-2.2/tests/test_model_bundle.py +401 -0
  135. altatts-2.2/tests/test_model_gates.py +403 -0
  136. altatts-2.2/tests/test_monitor_asr_check.py +58 -0
  137. altatts-2.2/tests/test_mos_backends.py +514 -0
  138. altatts-2.2/tests/test_pace_calibration.py +183 -0
  139. altatts-2.2/tests/test_phonemes.py +327 -0
  140. altatts-2.2/tests/test_pool_contexts.py +81 -0
  141. altatts-2.2/tests/test_prior_prompt.py +314 -0
  142. altatts-2.2/tests/test_prosody.py +189 -0
  143. altatts-2.2/tests/test_pseudo_speakers.py +388 -0
  144. altatts-2.2/tests/test_resume_determinism.py +451 -0
  145. altatts-2.2/tests/test_run6_followups.py +390 -0
  146. altatts-2.2/tests/test_sampler_fixed_point.py +135 -0
  147. altatts-2.2/tests/test_sampling.py +621 -0
  148. altatts-2.2/tests/test_selection.py +672 -0
  149. altatts-2.2/tests/test_serving.py +625 -0
  150. altatts-2.2/tests/test_serving_security.py +466 -0
  151. altatts-2.2/tests/test_speaker_encoders.py +548 -0
  152. altatts-2.2/tests/test_speaker_threshold.py +73 -0
  153. altatts-2.2/tests/test_staged.py +462 -0
  154. altatts-2.2/tests/test_streaming_boundaries.py +87 -0
  155. altatts-2.2/tests/test_text_frontend.py +544 -0
  156. altatts-2.2/tests/test_text_frontend_bundle.py +147 -0
  157. altatts-2.2/tests/test_text_names.py +380 -0
  158. altatts-2.2/tests/test_text_normalizer_v2.py +540 -0
  159. altatts-2.2/tests/test_text_normalizer_v3.py +168 -0
  160. altatts-2.2/tests/test_text_specials.py +117 -0
  161. altatts-2.2/tests/test_textqa.py +153 -0
  162. altatts-2.2/tests/test_textqa_flags.py +60 -0
  163. altatts-2.2/tests/test_train_resume_speakers.py +162 -0
  164. altatts-2.2/tests/test_trainer_audit_fixes.py +619 -0
  165. altatts-2.2/tests/test_trainer_gan_losses.py +192 -0
  166. altatts-2.2/tests/test_trainer_hygiene.py +348 -0
  167. altatts-2.2/tests/test_trainer_prior_gate.py +264 -0
  168. altatts-2.2/tests/test_trainer_schedule.py +195 -0
  169. altatts-2.2/tests/test_training_gates.py +334 -0
  170. altatts-2.2/tests/test_validate_data.py +177 -0
  171. altatts-2.2/tests/test_variance.py +326 -0
  172. altatts-2.2/tests/test_voice_plan.py +723 -0
  173. altatts-2.1.0/PKG-INFO +0 -316
  174. altatts-2.1.0/PYPI_README.md +0 -269
  175. altatts-2.1.0/README.md +0 -204
  176. altatts-2.1.0/altatts/benchmark.py +0 -165
  177. altatts-2.1.0/altatts/client.py +0 -94
  178. altatts-2.1.0/altatts/config.py +0 -492
  179. altatts-2.1.0/altatts/datasets/__init__.py +0 -24
  180. altatts-2.1.0/altatts/datasets/cli.py +0 -77
  181. altatts-2.1.0/altatts/deploy.py +0 -235
  182. altatts-2.1.0/altatts/export.py +0 -186
  183. altatts-2.1.0/altatts/inference/checkpoint.py +0 -115
  184. altatts-2.1.0/altatts/inference/evaluate.py +0 -388
  185. altatts-2.1.0/altatts/inference/streaming.py +0 -174
  186. altatts-2.1.0/altatts/inference/synthesizer.py +0 -435
  187. altatts-2.1.0/altatts/inference/voices.py +0 -120
  188. altatts-2.1.0/altatts/languages/__init__.py +0 -261
  189. altatts-2.1.0/altatts/languages/english.py +0 -79
  190. altatts-2.1.0/altatts/languages/french.py +0 -99
  191. altatts-2.1.0/altatts/languages/kinyarwanda.py +0 -114
  192. altatts-2.1.0/altatts/languages/swahili.py +0 -86
  193. altatts-2.1.0/altatts/lexicon.py +0 -298
  194. altatts-2.1.0/altatts/metrics.py +0 -314
  195. altatts-2.1.0/altatts/model/__init__.py +0 -19
  196. altatts-2.1.0/altatts/model/losses.py +0 -95
  197. altatts-2.1.0/altatts/model/meanflow.py +0 -305
  198. altatts-2.1.0/altatts/model/monotonic_align.py +0 -108
  199. altatts-2.1.0/altatts/model/style.py +0 -96
  200. altatts-2.1.0/altatts/model/vits.py +0 -366
  201. altatts-2.1.0/altatts/serving.py +0 -507
  202. altatts-2.1.0/altatts/speaker/__init__.py +0 -2
  203. altatts-2.1.0/altatts/speaker/enroll.py +0 -249
  204. altatts-2.1.0/altatts/text.py +0 -547
  205. altatts-2.1.0/altatts/training/anonymize.py +0 -459
  206. altatts-2.1.0/altatts/training/data.py +0 -595
  207. altatts-2.1.0/altatts/training/logging.py +0 -385
  208. altatts-2.1.0/altatts/training/train.py +0 -337
  209. altatts-2.1.0/altatts/training/trainer.py +0 -1077
  210. altatts-2.1.0/altatts.egg-info/PKG-INFO +0 -316
  211. altatts-2.1.0/altatts.egg-info/SOURCES.txt +0 -89
  212. altatts-2.1.0/tests/test_serving.py +0 -192
  213. altatts-2.1.0/tests/test_text_frontend.py +0 -143
  214. altatts-2.1.0/tests/test_voice_plan.py +0 -64
  215. {altatts-2.1.0 → altatts-2.2}/altatts/datasets/stats.py +0 -0
  216. {altatts-2.1.0 → altatts-2.2}/altatts/env/__init__.py +0 -0
  217. {altatts-2.1.0 → altatts-2.2}/altatts/env/compat_table.json +0 -0
  218. {altatts-2.1.0 → altatts-2.2}/altatts/env/distributed.py +0 -0
  219. {altatts-2.1.0 → altatts-2.2}/altatts/env/fix.py +0 -0
  220. {altatts-2.1.0 → altatts-2.2}/altatts/env/wheels.py +0 -0
  221. {altatts-2.1.0 → altatts-2.2}/altatts/inference/__init__.py +0 -0
  222. {altatts-2.1.0 → altatts-2.2}/altatts/integrations/__init__.py +0 -0
  223. {altatts-2.1.0 → altatts-2.2}/altatts/recipes/__init__.py +0 -0
  224. {altatts-2.1.0 → altatts-2.2}/altatts/training/__init__.py +0 -0
  225. {altatts-2.1.0 → altatts-2.2}/altatts/training/segment.py +0 -0
  226. {altatts-2.1.0 → altatts-2.2}/altatts.egg-info/dependency_links.txt +0 -0
  227. {altatts-2.1.0 → altatts-2.2}/altatts.egg-info/entry_points.txt +0 -0
  228. {altatts-2.1.0 → altatts-2.2}/altatts.egg-info/top_level.txt +0 -0
  229. {altatts-2.1.0 → altatts-2.2}/setup.cfg +0 -0
  230. {altatts-2.1.0 → altatts-2.2}/tests/test_datasets_pipeline.py +0 -0
  231. {altatts-2.1.0 → altatts-2.2}/tests/test_doctor.py +0 -0
  232. {altatts-2.1.0 → altatts-2.2}/tests/test_evaluate_helpers.py +0 -0
  233. {altatts-2.1.0 → altatts-2.2}/tests/test_per_category_validation.py +0 -0
  234. {altatts-2.1.0 → altatts-2.2}/tests/test_wheels.py +0 -0
altatts-2.2/PKG-INFO ADDED
@@ -0,0 +1,388 @@
1
+ Metadata-Version: 2.4
2
+ Name: altatts
3
+ Version: 2.2
4
+ Summary: ALTATTS: natural, expressive, multilingual text-to-speech with zero-shot voice cloning (builtin or frozen WavLM/ECAPA encoders, prompted MeanFlow prior), pitch/energy controls, emotion and pause control, IPA front end, anonymized default voices, windowed streaming -- 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
+ Requires-Dist: onnxscript>=0.3; extra == "onnx"
27
+ Provides-Extra: mms
28
+ Requires-Dist: transformers>=4.40; extra == "mms"
29
+ Provides-Extra: cloning
30
+ Requires-Dist: transformers>=4.40; extra == "cloning"
31
+ Provides-Extra: phonemes
32
+ Requires-Dist: phonemizer>=3.3; extra == "phonemes"
33
+ Requires-Dist: espeakng-loader>=0.2; extra == "phonemes"
34
+ Requires-Dist: gruut[fr]>=2.4; extra == "phonemes"
35
+ Provides-Extra: fast
36
+ Requires-Dist: numba>=0.58; extra == "fast"
37
+ Provides-Extra: data
38
+ Requires-Dist: pyarrow>=14; extra == "data"
39
+ Requires-Dist: openpyxl>=3.1; extra == "data"
40
+ Provides-Extra: logs
41
+ Requires-Dist: tensorboard>=2.14; extra == "logs"
42
+ Requires-Dist: matplotlib>=3.7; extra == "logs"
43
+ Provides-Extra: mos
44
+ Requires-Dist: distillmos>=0.1; extra == "mos"
45
+ Provides-Extra: dev
46
+ Requires-Dist: pytest>=8.0; extra == "dev"
47
+ Requires-Dist: pytest-timeout>=2.3; extra == "dev"
48
+ Provides-Extra: all
49
+ Requires-Dist: av>=11.0; extra == "all"
50
+ Requires-Dist: altasr>=1.1; extra == "all"
51
+ Requires-Dist: distillmos>=0.1; extra == "all"
52
+ Requires-Dist: onnx>=1.15; extra == "all"
53
+ Requires-Dist: onnxruntime>=1.17; extra == "all"
54
+ Requires-Dist: onnxscript>=0.3; extra == "all"
55
+ Requires-Dist: transformers>=4.40; extra == "all"
56
+ Requires-Dist: phonemizer>=3.3; extra == "all"
57
+ Requires-Dist: espeakng-loader>=0.2; extra == "all"
58
+ Requires-Dist: gruut[fr]>=2.4; extra == "all"
59
+ Requires-Dist: numba>=0.58; extra == "all"
60
+ Requires-Dist: pyarrow>=14; extra == "all"
61
+ Requires-Dist: openpyxl>=3.1; extra == "all"
62
+
63
+ # ALTATTS
64
+
65
+ **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.**
66
+
67
+ ALTATTS is the speaking half of the ALTA stack: [ALTASR](https://pypi.org/project/altasr/) listens, ALTATTS talks.
68
+
69
+ | capability | how |
70
+ |---|---|
71
+ | Natural prosody | **MeanFlow latent prior** (Geng, Deng, Bai, Kolter & He, 2025): the whole utterance is generated jointly in 1–4 steps |
72
+ | Word-exact speech | deterministic durations + monotonic alignment: no skipped or repeated words |
73
+ | Emotion and intensity | `emotion="happy", intensity=0.7` or inline `[calm]`, `[excited:0.8]`; 3.1: continuous `arousal` / `valence` on models trained with affect labels |
74
+ | Human behaviour | exact `[pause:0.5]`, natural `[pause]`, `[laugh]`, `[breath]`, `[sigh]`, hesitations |
75
+ | Voice cloning | enroll a speaker from a few seconds of audio, use it immediately, no training; 3.0: a frozen **WavLM / ECAPA** encoder (`style.speaker_encoder`) and **speaker prompts** for the MeanFlow prior (`style.prompt_encoder`); 3.2: reference clips are checked (3-30 s of clean wideband speech from one speaker; silence, hum, noise and clipping are refused with the measurement) and every enrolment records who attested the speaker's consent |
76
+ | Pitch and energy control (3.0) | `pitch_mode="predict"`, `pitch_scale`, `pitch_shift` (semitones), `energy_scale` on models trained with the variance adaptor |
77
+ | Pronunciation (3.0) | optional IPA front end for English / French (`text.phonemizer = espeak \| gruut`), learned pause buckets `[pause:short\|medium\|long]` |
78
+ | Low latency (3.0) | windowed streaming (first audio after one decoder window), warm-up, static per-stage ONNX export (`altatts-export --static`), `altatts-benchmark --ttfb` |
79
+ | Privacy | 12 anonymized **production voices** (French, English, Bantu groups: 2 F + 2 M each) verified against every training speaker; 3.2: the `callcenter_robust` recipe verifies in the frozen encoder's own space over five sentences and never serves a voice that failed |
80
+ | Code-switching | Kinyarwanda, English, French, Swahili in one model, word-level language detection, per-language number reading |
81
+ | Telephony | 8 kHz G.711 μ-law / A-law (ITU-T segment encoders since 3.1), 20 ms frames, Twilio messages, phrase streaming |
82
+ | Serving | `altatts serve` (REST + WebSocket, standard library only) and `altatts package` (Docker folder, `docker compose up`) |
83
+ | Anywhere | CPU, one GPU, all GPUs, several machines; `altatts doctor --fix` repairs PyTorch/CUDA/audio installs |
84
+
85
+ Every ALTATTS 0.1 interface still works and 0.1 checkpoints load unchanged;
86
+ every ALTATTS 3 capability is a config gate that defaults off, so 2.0 / 2.1
87
+ checkpoints load and sound exactly as before. ALTATTS 3.1 keeps the rule:
88
+ every new field defaults to the 3.0 behaviour, and a model folder trained
89
+ before 3.1 keeps reading text exactly as it was trained (its `config.json`
90
+ is stamped `text.rw_normalizer_version: 1` when loaded). ALTATTS 3.2 (the
91
+ 2026-10-28 audit) keeps the rule for models and training and changes
92
+ defaults only where the old behaviour was wrong or unsafe: the evaluation
93
+ numbers (section 8), the reference-audio checks (section 4) and the
94
+ server's policy (section 6); the details are in `CHANGELOG.md` 3.2.0.
95
+
96
+ ---
97
+
98
+ ## 1. Install and check
99
+
100
+ ```bash
101
+ pip install "altatts[av]" # av = mp3/webm/opus decoding; "altatts[all]" for everything
102
+ altatts doctor # Python / torch / CUDA / audio deps -> PASS/WARN/FAIL + fixes
103
+ altatts doctor --fix # repair what is safe (matched torch for your driver, missing deps)
104
+ ```
105
+
106
+ A plain `pip install torch` pulls the newest CUDA build (cu130 today), which
107
+ does not run on older drivers (a 570.x driver supports CUDA ≤ 12.8).
108
+ `altatts doctor --fix` cross-checks the driver's ceiling, the GPU's
109
+ compute-capability floor and the wheels actually published for your Python
110
+ and CPU architecture, prints the choice, installs the newest torch the
111
+ machine can run (exact pins, right index), re-verifies CUDA and rolls back
112
+ on failure. `--fix --dry-run` shows the cross-check without changing
113
+ anything; `--index-url cu126` forces an index. The manual equivalent:
114
+
115
+ ```bash
116
+ pip install --force-reinstall "torch==2.14.1+cu126" torchaudio --index-url https://download.pytorch.org/whl/cu126
117
+ python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
118
+ ```
119
+
120
+ ## 2. Which model do I have? ("generation")
121
+
122
+ A model folder's `config.json` carries `"model": {"version": N}`. This is only a **generation number**, never something you set by hand:
123
+
124
+ | generation | what it means | cloning / emotions / MeanFlow |
125
+ |---|---|---|
126
+ | **ALTATTS 2** (`version: 2`) | trained with altatts ≥ 2.0 (ALTATTS 3 keeps this generation: its gates are config options; `capabilities()` lists `prompt`, `variance`, `phonemizer`, `speaker_encoder`) | yes |
127
+ | **ALTATTS 0.1 (legacy)** (no `version` key) | trained with altatts 0.1, plain VITS | no, but every 0.1 call still works |
128
+
129
+ ```python
130
+ tts.capabilities()["generation"] # 'ALTATTS 2' or 'ALTATTS 0.1 (legacy VITS)'
131
+ ```
132
+
133
+ Upgrade a 0.1 model by fine-tuning: `altatts-train --init-from runs/old_model --preset base ...` (all VITS weights are reused).
134
+
135
+ ## 3. Synthesize
136
+
137
+ ```python
138
+ from altatts import Synthesizer
139
+
140
+ tts = Synthesizer.from_pretrained("runs/kin_v2")
141
+ wav, sr = tts.tts("Muraho! Amakuru yawe?", voice="female") # the 0.1 call
142
+ tts.tts_to_file("Murakaza neza.", "hello.wav", voice="male", sample_rate=8000)
143
+ print(tts.voices()) # production voices, enrolled voices, aliases
144
+ print(tts.capabilities()) # generation, emotions, languages, cloning, pause token ...
145
+ ```
146
+
147
+ ### Every control, and the value that works best
148
+
149
+ | parameter | values | best practice |
150
+ |---|---|---|
151
+ | `voice` | `female`, `male`, `bantu_female_1`, `french_male_2`, `english_female_1`, `fr_female`, `kin_male`, an enrolled name, **or a path to a reference clip** (Python / CLI only) | pick the group that matches the sentence language; `female`/`male` are the primary-language voices. On a production folder (one with anonymized voices) training speakers are not reachable by name -- evaluation code passes `allow_training_speakers=True` explicitly, and a `female` / `male` alias without an anonymized voice of that gender raises instead of serving a real speaker (3.1) |
152
+ | `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"]`) |
153
+ | `intensity` | 0–1 | 0.3 subtle, **0.6 natural**, 1.0 strong |
154
+ | `speed` | 0.5–2 | **1.0**; 0.95 for instructions/health lines, 1.05–1.1 for busy IVR menus |
155
+ | `noise_scale` | 0–1 | **0.667** (standard); 0.5 for maximally consistent prompts, 0.8 for lively narration |
156
+ | `steps` | 1–8 | **4** default; 1 = fastest (CPU/live), 8 = maximum naturalness for pre-rendered media -- read only with `prior="meanflow"` (every recipe serves `flow`, where `steps` is a no-op) |
157
+ | `cfg_scale` | 1–2 | **1.0**; classifier-free guidance of the MeanFlow prior, read only with `prior="meanflow"` -- on the flow path it does nothing, and a cloned identity is improved by a better reference clip (section 4), not by this knob |
158
+ | `seed` | int | set it for reproducible prompts (same text → same audio) |
159
+ | `sample_rate` | 8000 … 48000 | 8000 telephony, 16000 ASR/voice bots, 22050 native, 48000 media |
160
+ | `language` | `rw en fr sw` (`kin eng fra swa` accepted) | since 3.1 the default follows the sentence (the language most of its words give evidence for), so an English sentence on a Kinyarwanda-first model is read as English without the flag; set it to force one; mixed text is detected word by word; force spans with `<en>…</en>` |
161
+ | `pause_scale` | float | multiplies every `[pause:x]` |
162
+ | `reference_audio` (+ `reference_sr` for arrays) | path, array, `(array, sr)` or a list of clips | one-off cloning from a clip; 3-30 s of clean wideband speech from one speaker (5-10 s is the sweet spot); since 3.2 a silent, hum, noise, clipped, too-short or corrupt clip raises `ReferenceAudioError` with the measurement, and anything beyond 30 s is cropped |
163
+ | `speaker_embedding` | vector from `tts.embed_speaker(...)` | fastest repeated cloning (embed once, reuse); the vector must be a flat list of exactly `gin_channels` finite floats (the server refuses the field unless started with `--allow-embeddings`) |
164
+ | `prior` | `flow` / `meanflow` | `flow` is the default everywhere (the VITS path); `meanflow` samples the trained MeanFlow prior in 1–4 steps, worth an A/B once `mf` in the epoch table has settled |
165
+ | `duration_noise` | 0 – 0.3 | rhythm variation (log-duration jitter); the recipe default 0.1 sounds human, 0 is metronomic, 0.3 lively — seeded with `seed` |
166
+ | `prompt` (3.0) | another clip of the speaker, `tts.embed_prompt(clips)` or a tensor | speaker prompt for the prompted MeanFlow prior (`prior="meanflow"`); enrolled voices carry their own, production voices use the trained null prompt |
167
+ | `blank_scale` (3.2) | 0.5 – 1.5 | **1.0**; shortens or lengthens only the gaps on the blank tokens between letters, leaving pauses and letters alone (`speed` scales everything) |
168
+ | `heun`, `t0`, `chunk_frames`, `chunk_overlap`, `prompt_crop` (3.2) | sampler knobs | read with `prior="meanflow"` only (default: the folder's `prior.*` config); on the flow path every recipe serves, these and `steps` / `cfg_scale` print one warning and do nothing |
169
+ | `pitch_mode` (3.0) | `null` / `predict` | **`null`** (the trained pitch-free path); `predict` uses the variance adaptor's contours — livelier, slightly less predictable |
170
+ | `pitch_scale` (3.0) | 0.7 – 1.5 | **1.0**; 1.2–1.3 more pitch movement for narration, 0.8 flatter for calm service lines (switches to `predict`) |
171
+ | `pitch_shift` (3.0) | −4 … +4 semitones | **0**; ±1–2 to nudge a voice higher or lower (approximate) |
172
+ | `energy_scale` (3.0) | 0.8 – 1.3 | **1.0**; 1.1 for a more projected voice |
173
+ | `arousal`, `valence` (3.1) | −1 … 1 each | only on models trained with `style.affect = "av"` (`capabilities()["affect"]`): arousal −1 flat and quiet, 1 lively; valence −1 negative, 1 positive; a missing one is 0; other models ignore them with one warning |
174
+
175
+ ### Scenarios with their best configurations
176
+
177
+ ```python
178
+ # A. Call-center / IVR prompts (pre-rendered, 8 kHz, identical every time)
179
+ wav, sr = tts.tts("Murakaza neza kuri banki yacu. [pause:0.4] Kanda rimwe ku konti yawe.",
180
+ voice="bantu_female_1", emotion="calm", intensity=0.5,
181
+ speed=0.97, noise_scale=0.5, steps=8, seed=1, sample_rate=8000)
182
+ ulaw = tts.mulaw_bytes("Murakoze guhamagara.", voice="female", emotion="calm", seed=1)
183
+
184
+ # B. Live voice agent (lowest latency; stream phrase by phrase, see §5)
185
+ wav, sr = tts.tts("Yego, ndabikora nonaha.", voice="female", steps=2, sample_rate=16000)
186
+
187
+ # C. Media / audiobook narration (maximum naturalness)
188
+ wav, sr = tts.tts("Umwana yarahagurutse, [breath] areba hirya no hino, [pause:0.8] "
189
+ "maze aratangira kwiruka.", voice="bantu_male_2", emotion="excited",
190
+ intensity=0.6, noise_scale=0.8, steps=8, sample_rate=48000)
191
+
192
+ # D. Emotion sweep (faint -> ecstatic) on the same sentence
193
+ for inten in (0.2, 0.5, 0.8, 1.0):
194
+ wav, sr = tts.tts("Twishimiye cyane kubabona!", voice="female",
195
+ emotion="happy", intensity=inten, seed=3)
196
+
197
+ # E. Code-switching and numbers (read in each sentence's language)
198
+ wav, sr = tts.tts("Konti yawe ifite FRW 2,500. <en>Your balance is 2,500 francs.</en> "
199
+ "Votre solde est de 2500 FRW. Salio lako ni FRW 2500.",
200
+ voice="bantu_female_2", steps=4)
201
+ wav, sr = tts.tts("Bonjour, votre dossier est prêt.", voice="french_female_1", language="fr")
202
+ wav, sr = tts.tts("Habari, akaunti yako iko tayari.", voice="bantu_male_1", language="sw")
203
+
204
+ # F. Human behaviour tags
205
+ wav, sr = tts.tts("Hmm [hesitation] ndabona. [pause:0.6] [laugh] Nibyo rwose! [breath] Reka nkwereke.",
206
+ voice="male", emotion="happy", intensity=0.5)
207
+
208
+ # G. Cloning: one-off, by path, enrolled
209
+ wav, sr = tts.tts("Muraho neza.", reference_audio=["agent_1.wav", "agent_2.wav"]) # 3-30 s of clean speech each
210
+ wav, sr = tts.tts("Muraho neza.", voice="agent_1.wav")
211
+ tts.enroll_speaker("agent_claire", ["claire_1.wav", "claire_2.wav"], gender="female",
212
+ consent={"attested_by": "J. Uwase (team lead)", "method": "signed form"})
213
+ wav, sr = tts.tts("Murakoze guhamagara.", voice="agent_claire", emotion="calm", intensity=0.4)
214
+
215
+ # G'. Continuous affect (3.1; models trained with style.affect = "av")
216
+ wav, sr = tts.tts("Twishimiye kubabona!", voice="female", arousal=0.6, valence=0.4)
217
+
218
+ # H. Fastest CPU synthesis
219
+ wav, sr = tts.tts("Muraho neza.", voice="female", steps=1)
220
+
221
+ # I. Explain how a text will be read (QA before shipping prompts)
222
+ print(tts.analyze("Konti 0788123456 ifite FRW 2,500. <en>Thank you.</en>")["plan"])
223
+ ```
224
+
225
+ 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`, and in 3.0 `--pitch-mode predict --pitch-scale 1.2 --pitch-shift 1 --energy-scale 1.1 --prompt-audio other_take.wav --prior meanflow`, and in 3.2 `--blank-scale 0.8`, `--heun on --t0 0.99 --chunk-frames 512 --chunk-overlap 64 --prompt-crop on` (MeanFlow sampler only).
226
+
227
+ ## 4. Voices: production, enrolled, cloned
228
+
229
+ 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:
230
+
231
+ | group | languages | voices |
232
+ |---|---|---|
233
+ | `bantu` | Kinyarwanda, Swahili, code-switching | `bantu_female_1`, `bantu_female_2`, `bantu_male_1`, `bantu_male_2` |
234
+ | `french` | French | `french_female_1/2`, `french_male_1/2` |
235
+ | `english` | English | `english_female_1/2`, `english_male_1/2` |
236
+
237
+ 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.
238
+
239
+ ```bash
240
+ altatts voices list --model runs/kin_v2
241
+ altatts-enroll --model runs/kin_v2 --name agent_claire --audio c1.wav c2.wav --gender female \
242
+ --consent-attested-by "J. Uwase (team lead)" --consent-method "signed form"
243
+ altatts-enroll --model runs/kin_v2 --name agent_claire --audio c1.wav --text "Muraho neza." --adapt-steps 300 \
244
+ --consent-attested-by "J. Uwase"
245
+ ```
246
+
247
+ Since 3.2 `altatts-enroll` and the HTTP API refuse an enrolment without a
248
+ consent attestation (`--consent-attested-by NAME`, optionally
249
+ `--consent-method` and `--consent-reference`; the Python API records
250
+ `consent=` when given); the record is stored with the voice in
251
+ `voices.json`, and the clip paths are not (`--keep-source-paths` keeps
252
+ them).
253
+
254
+ Since 3.1 a production model never serves one of its training speakers: `tts.voices()` lists only anonymized and enrolled voices, a training speaker's name raises, and `female` / `male` need an anonymized voice of that gender (`altatts voices build` creates them; `altatts serve` / `altatts package` warn when a folder has none). A model with an intensity trained as `neutral_mix` (the `callcenter_robust` recipe) reads `intensity` as the distance from the voice's neutral delivery: 0 is neutral, 1 the full emotion.
255
+
256
+ Enrollment tips: 3-30 s of clean **wideband** speech per clip (5-10 s is the sweet spot; identity does not improve beyond ~20 s and clips are cropped to 30 s), one speaker, no music, several clips, the same microphone as production -- a silent, hum, noise or clipped clip is refused with the measurement and the fix (`ReferenceAudioError`, 422 on the server); `--adapt-steps` (few-shot) when the model saw few training speakers; `cfg_scale` acts on `prior="meanflow"` only. Judge a clone in the frozen encoder's own space (`altatts.speaker.similarity.speaker_similarity(..., space="raw")`, `altatts evaluate-cloning`), not in the model's style space. A production voice that failed its privacy verification (`privacy_report.json`, `passed: false`) is still served unless the folder's config says `style.serve_unverified_voices: false` (the recipe does); `altatts package` warns loudly when every voice failed. ALTATTS 3 models: the same commands work with the frozen WavLM / ECAPA encoder (`pip install "altatts[cloning]"`, weights cached once), the clip's prompt tokens are stored with the voice (`--no-prompt` to skip) and `altatts voices build --candidate-rule top4 --n-candidates 4` picks production voices from the best-covered speakers with a naturalness gate.
257
+
258
+ ## 5. Live streaming
259
+
260
+ ```python
261
+ from altatts import Synthesizer, StreamingSynthesizer
262
+
263
+ tts = Synthesizer.from_pretrained("runs/kin_v2")
264
+ stream = StreamingSynthesizer(tts, voice="female", sample_rate=8000,
265
+ emotion="calm", intensity=0.5, steps=2) # live settings
266
+
267
+ # known text: audio starts after the FIRST sentence
268
+ for chunk in stream.stream("Muraho. [pause:0.3] Turabafasha gute uyu munsi?"):
269
+ send_to_caller(chunk) # float32; exact pauses arrive as silent chunks
270
+
271
+ # LLM token stream: speak each sentence as soon as it completes
272
+ for token in llm_tokens:
273
+ for chunk in stream.feed(token):
274
+ send_to_caller(chunk)
275
+ for chunk in stream.flush():
276
+ send_to_caller(chunk)
277
+ print(stream.first_chunk_latency_s)
278
+ stream.reset(voice="male", emotion="happy")
279
+ ```
280
+
281
+ 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`.
282
+
283
+ Windowed mode (3.0, opt-in): `StreamingSynthesizer(tts, ..., windowed=True, window_frames=48, context_frames=20)` yields the decoder output window by window (≈ 0.56 s each) so the first audio no longer waits for the whole phrase; call `stream.warmup()` once at start-up. Targets: GPU warm 20–45 ms to the first window, CPU ≈ 0.5 s with the recipe's 768-channel decoder. `altatts-benchmark --models runs/kin_v2 --ttfb` measures both paths.
284
+
285
+ ## 6. Serve it as an API and deploy with one command
286
+
287
+ ```bash
288
+ altatts serve --model runs/kin_v2 --port 8081 # REST + WebSocket, no extra packages; voice management OFF
289
+ altatts serve --model runs/kin_v2 --port 8081 --enable-enroll --admin-token "$ALTATTS_ADMIN_TOKEN" \
290
+ --audit-log /srv/tts/audit.jsonl # enrol / delete / reload behind a bearer token
291
+ ```
292
+
293
+ | endpoint | purpose |
294
+ |---|---|
295
+ | `GET /health`, `/capabilities`, `/voices` | status, what the model can do, voice list |
296
+ | `GET /tts?text=…&voice=…` | quick test → WAV |
297
+ | `POST /tts` | JSON request → `wav` / `pcm16` / `mulaw` / `alaw` bytes, or `format: "json"` (base64) |
298
+ | `POST /tts/stream` | chunked audio, one chunk per phrase (first bytes after the first sentence) |
299
+ | `WS /ws` | live streaming: send `{"text": …}` or `{"reset": …}` + `{"feed": "token"}` … `{"flush": true}`; receive binary chunks |
300
+ | `POST /voices/enroll`, `DELETE /voices/<name>`, `POST /reload` | add / remove voices at runtime, reload the folder -- off by default since 3.2: start with `--enable-enroll --admin-token <secret>` (or `ALTATTS_ENABLE_ENROLL=1` + `ALTATTS_ADMIN_TOKEN`), send `Authorization: Bearer <secret>` (401 without, 403 while off), and attest consent per voice (`"consent": {"attested_by": ...}`, 422 without); production voices, aliases and training-speaker names can never be overwritten or deleted (409) |
301
+ | `POST /analyze` | normalization + synthesis plan for QA |
302
+
303
+ Request fields = the Python parameters (`text, voice, emotion, intensity, language, sample_rate, format, speed, noise_scale, steps, cfg_scale, seed, pause_scale, prior, duration_noise, prosody, reference`, in 3.0 `pitch_mode, pitch_scale, pitch_shift, energy_scale`, in 3.1 `arousal, valence`; `speaker_embedding` only when the server runs with `--allow-embeddings`; streaming requests also `windowed, window_frames, context_frames`; `steps` and `cfg_scale` act on `prior="meanflow"` only). `GET /capabilities` lists them with the server's policy and limits (`server`). The lock is held per model call (a CPU runs one at a time, `--concurrency N` on a GPU), so a long stream never stalls other clients. Limits: text up to 5,000 characters, JSON bodies up to 1 MB, enrolment bodies up to 32 MB (**413** beyond), a body that stalls for 60 s gets **408**, WebSocket frames up to 16 MB; since 3.2 every numeric field is bounded (speed 0.25-4, noise_scale 0-2, steps 1-16, cfg_scale 0-4, pause_scale 0-4, ... -> 422 naming the field and its range), the planned output is capped (`--max-output-seconds`, 600), a request that waits more than `--queue-timeout` (120 s) for the model gets **503**, `mulaw` / `alaw` are served at 8 kHz only, server faults are a generic 500 (the detail goes to the log), CORS is off unless `--cors-origin` lists the origin, and `--cloning enrolled` limits cloning to enrolled voices; `/tts/stream` validates the voice, emotion and text before it answers 200, so a typo is a clean 422; a `voice` can never be a file path on the server (enroll it or send `reference`), a hidden training speaker is never served, and a `reference` clip goes through the same checks as an enrolment (422 with the measurement).
304
+
305
+ ```bash
306
+ curl -s localhost:8081/tts -H 'Content-Type: application/json' -d '{
307
+ "text": "Murakaza neza. [pause:0.4] Twishimiye kubafasha!",
308
+ "voice": "bantu_female_1", "emotion": "calm", "intensity": 0.5,
309
+ "sample_rate": 8000, "format": "mulaw", "seed": 1 }' -o prompt.ulaw
310
+ curl -sN localhost:8081/tts/stream -H 'Content-Type: application/json' \
311
+ -d '{"text": "Muraho. Amakuru yawe?", "voice": "female", "sample_rate": 16000}' > live.pcm
312
+ ```
313
+
314
+ ```python
315
+ from altatts.client import TTSClient # standard library client
316
+ api = TTSClient("http://tts.internal:8081")
317
+ wav, sr = api.tts("Muraho neza.", voice="female", emotion="calm")
318
+ for chunk in api.stream("Muraho. Amakuru?", sample_rate=8000, format="mulaw"):
319
+ rtp_send(chunk)
320
+ admin = TTSClient("http://tts.internal:8081", token="<the admin token>") # enrol / delete need the token
321
+ admin.enroll("agent_claire", ["c1.wav", "c2.wav"], gender="female",
322
+ consent={"attested_by": "J. Uwase (team lead)", "method": "signed form"})
323
+ ```
324
+
325
+ **Deploy on a server** (model + Dockerfile + compose + README generated for you):
326
+
327
+ ```bash
328
+ altatts package --model runs/kin_v2 --out deploy/altatts-api # add --gpu for a CUDA image
329
+ scp -r deploy/altatts-api server:/srv/ && ssh server 'cd /srv/altatts-api && docker compose up -d'
330
+ curl -s server:8081/health
331
+ ```
332
+
333
+ Enrolled voices persist (the `model/` directory is bind-mounted from the host; the container runs as uid 1000 since 3.2, so `chown -R 1000:1000 model`). The Dockerfile installs the extras the model needs (`altatts[av,phonemes,cloning]` for the recipes; 3.1 reads them from `config.json`, and `altatts package` refuses a folder it cannot load locally) and since 3.2 pins torch to the version the load was verified with. Voice management stays OFF in the container until `.env` sets both `ALTATTS_ENABLE_ENROLL=1` and `ALTATTS_ADMIN_TOKEN`; `ALTATTS_AUDIT_LOG` (set by default to `/app/model/audit.jsonl`) records enrol / delete / reload / reference events without audio or text; `privacy_report.json` (it names training speakers) is never shipped, and a folder without anonymized production voices is refused unless `--allow-training-speakers`. The container port is pinned in the image; publish it elsewhere with `HOST_PORT=9000 docker compose up -d` (`.env`). Put the service behind your reverse proxy; keep the admin token out of the image; run one instance per GPU or CPU socket and load-balance for throughput.
334
+
335
+ ## 7. Call centers
336
+
337
+ ```python
338
+ from altatts.integrations.callcenter import (telephony_frames, streaming_telephony_frames,
339
+ twilio_media_messages, VoiceAgent,
340
+ prerender_prompts, enroll_agent)
341
+ for frame in telephony_frames(tts, "Murakoze guhamagara.", voice="female", emotion="calm"):
342
+ rtp_send(frame) # 160-byte G.711 frames
343
+ agent = VoiceAgent(asr, tts, respond_fn=my_bot, voice="agent_eric", emotion="calm", steps=2)
344
+ prerender_prompts(tts, {"welcome": "Murakaza neza.", "menu": "Kanda rimwe ..."},
345
+ out_dir="ivr/", voice="bantu_female_1", emotion="calm", seed=1)
346
+ ```
347
+
348
+ G.711 note (3.1): `mulaw_bytes` / `alaw_bytes`, the `mulaw` / `alaw` server formats and the frame helpers now produce the standard ITU-T G.711 segment encoding (bit-exact with the reference tables; digital silence 0xFF / 0xD5). The 3.0 bytes decoded to noise on a real PCMU / PCMA trunk, so re-render prompts you pre-encoded with altatts ≤ 3.0.0; `altatts.audio.from_mulaw` / `from_alaw` decode.
349
+
350
+ ## 8. Train on your data
351
+
352
+ 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`).
353
+
354
+ ```bash
355
+ altatts-prepare-data --metadata fr.jsonl en.jsonl rw.jsonl sw.jsonl cs.jsonl --audio-root /data \
356
+ --out /data/tts/train.jsonl --languages rw en fr sw --auto-pauses punct --convert-audio flac
357
+ altatts-train --recipe multilingual_callcenter --gpus all \
358
+ --train-metadata /data/tts/train_converted.jsonl --val-metadata /data/tts/val_converted.jsonl \
359
+ --audio-root /data/tts/audio_flac --out runs/kin_v2
360
+ altatts validate-data /data/tts --config altatts/recipes/callcenter_robust.json # before the run: exit 2 = errors
361
+ altatts-evaluate --model runs/kin_v2 --metadata test.jsonl --audio-root /data \
362
+ --asr-model /path/altasr --target-wer 0.05 --robustness --clone --out eval/report.json
363
+ altatts evaluate-cloning --model runs/kin_v2 --pool cloning_pool/manifest.jsonl \
364
+ --asr-model /path/altasr --multi-ref --out eval/cloning.json
365
+ ```
366
+
367
+ Since 3.2 the ALTASR judge is called with formatting and inverse text normalisation off and its hypothesis goes through the same normaliser as the reference, so a sentence with a number can reach WER 0 (every earlier WER was biased upward). `--target-wer` is a WER **delta**: the synthesized clips' WER minus the judge's own WER on the test recordings (transcribed once, cached), so the judge's errors are not charged to the voice; the robustness blocks gate per language too, and any row that failed to synthesize or transcribe fails the gate (`--target-wer-absolute` gates on the absolute WER instead). `--clone` conditions on *another* clip of each speaker and reports speaker similarity in two spaces against a real-vs-real ceiling; `altatts evaluate-cloning` measures zero-shot cloning on a speaker pool (seen and unseen speakers, one / four references, reference length, a wrong-reference control, the production voices as the no-reference baseline; identification, EER, consistency, transcript leakage, WER, bootstrap intervals; `docs/USAGE.md` section 14). MCD is on the package's own scale since 3.2 (not the literature's 4-7 dB) and CER counts spaces: compare numbers across the same version only.
368
+
369
+ 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. The 3.0 gates (`--speaker-encoder wavlm`, `--phonemizer espeak`, `--prompt-encoder builtin`, `model.variance_adaptor`, `model.disc_msstftd`, `train.speaker_adversarial`) are all on in the recipe and all off in the presets; turning one on for an existing run means `--init-from <old folder>` into a new `--out` folder (`docs/USAGE.md` section 20). 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 the selection metric stops improving; `altatts logs --run runs/x` summarises a run.
370
+
371
+ The `callcenter_robust` recipe (3.1) picks `best.pt` and stops on the **inference-path monitor** -- a composite of WER, CER, duration ratio, pitch variation and MCD measured on synthesized dev clips, with hard gates -- so pass `--monitor-asr-model <ALTASR folder>` (without it the run refuses to start unless `--allow-no-asr`); its stability guard watches the GAN's own signatures and reloads `last_good.pt` with only the discriminator slowed down; the alignment search runs as a GPU kernel (`train.mas_backend = auto`, nothing to install); and checkpoints are atomic with a true mid-epoch resume (a kill, a SIGTERM or Ctrl-C loses nothing). Install the server with `pip install "altatts[av,fast,phonemes,cloning,asr]"` plus `pip install distillmos` for the naturalness gate. Audio-derived emotion labels for a kit: `altatts label-emotions --kit <kit>` writes `<kit>/labels/emotion_ser.jsonl`, merged at training time through `data.label_files` (development tool, nothing of it ships in a model). Folders trained before 3.1 keep their text reading (`text.rw_normalizer_version` 1 is stamped on load); new runs read Kinyarwanda numbers with noun-class agreement and acronyms by their letter names, and carry those tables in `frontend/`. The test suite (`pip install "altatts[dev]"`, `python -m pytest tests -q`) runs in about 4 minutes on the dev box and needs no deselection.
372
+
373
+ ## 9. Troubleshooting
374
+
375
+ - Anything environment-related: `altatts doctor` → `altatts doctor --fix`.
376
+ - `voice cloning needs an ALTATTS 2 model`: a 0.1 folder; upgrade with `--init-from`.
377
+ - Emotion has no audible effect: not in the training labels; label a subset and fine-tune; raise `intensity` (`cfg_scale` acts on `prior="meanflow"` only).
378
+ - `ReferenceAudioError: ... is silent / is too short / is clipped / a hum or a DC offset` (422 on the server): the reference clip failed the 3.2 checks; record 3-30 s of clean wideband speech from one speaker.
379
+ - `POST /voices/enroll` / `DELETE /voices/<name>` / `POST /reload` answer 403 or 401: voice management is off by default since 3.2; start the server with `--enable-enroll --admin-token <secret>` and send `Authorization: Bearer <secret>`; 422 `ConsentRequired` = add the `consent` object; `altatts-enroll` exits 2 without `--consent-attested-by`.
380
+ - `refusing to resume ...: the stability guard STOPPED this run` (3.2): warm-start a new folder with `--init-from`, or pass `--resume-after-stop` (`train.resume_after_stop: true` / `ALTATTS_RESUME_AFTER_STOP=1`) knowingly.
381
+ - A production voice is flagged in `privacy_report.json`: rebuild with `altatts voices build --seed N` or add speakers of that gender/family.
382
+ - Slow on CPU: `steps=1`, `--preset small`, pre-render fixed prompts, windowed streaming, or deploy the API on a GPU box.
383
+ - `text.phonemizer=... not installed` / `external speaker encoder`: `pip install "altatts[phonemes]"` / `"altatts[cloning]"`; `altatts doctor --checkpoint <folder>` names what a model needs.
384
+ - `voice 'female': voices.json has no anonymized default voice for this gender` (3.1): build the production voices (`altatts voices build --model <folder>`) or enroll a voice; a training speaker is never substituted.
385
+ - The API answers 413 / 408: the request is over a limit (text 5,000 characters, JSON 1 MB, enrolment 32 MB) or stalled for 60 s; split or stream the text.
386
+ - `[mas] backend=numpy ... on cuda:0` in the training log: the GPU alignment kernel was not usable (the line says why); `pip install "altatts[fast]"` gives the numba fallback; `altatts doctor` has a row for it.
387
+
388
+ Full manual: `docs/USAGE.md`. Dataset guide: `docs/DATASET.md`. Apache-2.0 · YaliLabs / ALTA Project