Add multi-speaker 3-speaker epoch-10 inference bundle

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+references/hausa_fe_naijavoices_O0456.wav filter=lfs diff=lfs merge=lfs -text
+references/hausa_fe_waxal_nlp_3.wav filter=lfs diff=lfs merge=lfs -text
+references/hausa_fe_waxal_nlp_5.wav filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,60 @@
+---
+license: other
+language:
+  - ha
+tags:
+  - text-to-speech
+  - xtts
+  - hausa
+  - coqui
+library_name: coqui-tts
+---
+
+# XTTS-v2 Hausa — multi-speaker (3 speakers, 10 epochs)
+
+Fine-tuned [Coqui XTTS-v2](https://huggingface.co/coqui/XTTS-v2) for Hausa (`ha`), trained on
+`vaghawan/hausa-tts-24khz-waxalnlp-3-clean`, `vaghawan/hausa-tts-24khz-waxalnlp-5-clean`, `vaghawan/hausa-tts-24khz-naijavoices-O0456`.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `best_model.pth` | Fine-tuned GPT checkpoint (epoch 10) |
+| `config.json` | Model config (includes Hausa language) |
+| `vocab.json` | Extended Hausa BPE vocabulary |
+| `references/hausa_fe_waxal_nlp_3.wav` | Speaker reference for `hausa_fe_waxal_nlp_3` |
+| `references/hausa_fe_waxal_nlp_5.wav` | Speaker reference for `hausa_fe_waxal_nlp_5` |
+| `references/hausa_fe_naijavoices_O0456.wav` | Speaker reference for `hausa_fe_naijavoices_O0456` |
+| `infer.py` | Inference script |
+| `xtts_hausa_patch.py` | Required Hausa runtime patches |
+| `env_config.py` | Config loader |
+| `config.env.example` | Example settings (copy to `config.env`) |
+| `samples.txt` | Default eval sentences |
+| `requirements.txt` | Python dependencies |
+
+## Quick start
+
+```bash
+pip install -r requirements.txt
+cp config.env.example config.env
+
+python infer.py --model-dir . --speaker-wav references/hausa_fe_waxal_nlp_3.wav
+
+# Single line:
+python infer.py --model-dir . --text "Ina kwana." --speaker-wav references/hausa_fe_waxal_nlp_3.wav --out outputs/out.wav
+```
+
+# All speakers (one WAV per reference):
+python infer.py --model-dir . --all-speakers --out-dir outputs/samples
+
+## Training details
+
+- Base model: Coqui XTTS-v2
+- Epochs: 10
+- Language: Hausa (`ha`)
+- Speakers: `hausa_fe_waxal_nlp_3`, `hausa_fe_waxal_nlp_5`, `hausa_fe_naijavoices_O0456`
+
+## License
+
+XTTS-v2 uses the [Coqui Public Model License](https://huggingface.co/coqui/XTTS-v2).
+Check each dataset license before redistribution.

best_model.pth

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

config.env.example

@@ -0,0 +1,13 @@
+# Inference config for this Hugging Face repo (copy to config.env)
+LANGUAGE=ha
+SPEAKER_IDS=hausa_fe_waxal_nlp_3 hausa_fe_waxal_nlp_5 hausa_fe_naijavoices_O0456
+SPEAKER_REF=references/hausa_fe_waxal_nlp_3.wav
+SAMPLES_FILE=samples.txt
+INFER_OUT_DIR=outputs/samples
+INFER_OUT=outputs/out.wav
+INFER_ALL_SPEAKERS=true
+TEMPERATURE=0.7
+LENGTH_PENALTY=1.0
+REPETITION_PENALTY=5.0
+TOP_K=50
+TOP_P=0.85

config.json

@@ -0,0 +1,207 @@
+{
+    "output_path": "/workspace/mtn-tts-tests/xtts-v2/checkpoints/run/training",
+    "logger_uri": null,
+    "run_name": "GPT_XTTS_v2_Hausa_FT_multi_speaker",
+    "project_name": "XTTS_trainer",
+    "run_description": "XTTS-v2 GPT fine-tune on Hausa (WaxalNLP)",
+    "print_step": 25,
+    "plot_step": 100,
+    "model_param_stats": false,
+    "wandb_entity": null,
+    "dashboard_logger": "tensorboard",
+    "save_on_interrupt": true,
+    "log_model_step": 100,
+    "save_step": 500,
+    "save_n_checkpoints": 2,
+    "save_checkpoints": true,
+    "save_all_best": false,
+    "save_best_after": 0,
+    "target_loss": null,
+    "print_eval": true,
+    "test_delay_epochs": 0,
+    "run_eval": true,
+    "run_eval_steps": null,
+    "distributed_backend": "nccl",
+    "distributed_url": "tcp://localhost:54321",
+    "mixed_precision": false,
+    "precision": "fp16",
+    "epochs": 10,
+    "batch_size": 2,
+    "eval_batch_size": 2,
+    "grad_clip": 0.0,
+    "scheduler_after_epoch": true,
+    "lr": 5e-06,
+    "optimizer": "AdamW",
+    "optimizer_params": {
+        "betas": [
+            0.9,
+            0.96
+        ],
+        "eps": 1e-08,
+        "weight_decay": 0.01
+    },
+    "lr_scheduler": "MultiStepLR",
+    "lr_scheduler_params": {
+        "milestones": [
+            900000,
+            2700000,
+            5400000
+        ],
+        "gamma": 0.5,
+        "last_epoch": -1
+    },
+    "use_grad_scaler": false,
+    "allow_tf32": false,
+    "cudnn_enable": true,
+    "cudnn_deterministic": false,
+    "cudnn_benchmark": false,
+    "training_seed": 1,
+    "model": "xtts",
+    "num_loader_workers": 4,
+    "num_eval_loader_workers": 0,
+    "use_noise_augment": false,
+    "audio": {
+        "sample_rate": 22050,
+        "output_sample_rate": 24000,
+        "dvae_sample_rate": 22050
+    },
+    "model_args": {
+        "gpt_batch_size": 1,
+        "enable_redaction": false,
+        "kv_cache": true,
+        "gpt_checkpoint": "",
+        "clvp_checkpoint": null,
+        "decoder_checkpoint": null,
+        "num_chars": 255,
+        "tokenizer_file": "/workspace/mtn-tts-tests/xtts-v2/checkpoints/XTTS_v2.0_original_model_files/vocab.json",
+        "gpt_max_audio_tokens": 605,
+        "gpt_max_text_tokens": 402,
+        "gpt_max_prompt_tokens": 70,
+        "gpt_layers": 30,
+        "gpt_n_model_channels": 1024,
+        "gpt_n_heads": 16,
+        "gpt_number_text_tokens": 8238,
+        "gpt_start_text_token": 261,
+        "gpt_stop_text_token": 0,
+        "gpt_num_audio_tokens": 1026,
+        "gpt_start_audio_token": 1024,
+        "gpt_stop_audio_token": 1025,
+        "gpt_code_stride_len": 1024,
+        "gpt_use_masking_gt_prompt_approach": true,
+        "gpt_use_perceiver_resampler": true,
+        "input_sample_rate": 22050,
+        "output_sample_rate": 24000,
+        "output_hop_length": 256,
+        "decoder_input_dim": 1024,
+        "d_vector_dim": 512,
+        "cond_d_vector_in_each_upsampling_layer": true,
+        "duration_const": 102400,
+        "min_conditioning_length": 11025,
+        "max_conditioning_length": 132300,
+        "gpt_loss_text_ce_weight": 0.01,
+        "gpt_loss_mel_ce_weight": 1.0,
+        "debug_loading_failures": true,
+        "max_wav_length": 330750,
+        "max_text_length": 250,
+        "mel_norm_file": "/workspace/mtn-tts-tests/xtts-v2/checkpoints/XTTS_v2.0_original_model_files/mel_stats.pth",
+        "dvae_checkpoint": "/workspace/mtn-tts-tests/xtts-v2/checkpoints/XTTS_v2.0_original_model_files/dvae.pth",
+        "xtts_checkpoint": "/workspace/mtn-tts-tests/xtts-v2/checkpoints/XTTS_v2.0_original_model_files/model.pth",
+        "vocoder": ""
+    },
+    "_supports_cloning": true,
+    "use_phonemes": false,
+    "phonemizer": null,
+    "phoneme_language": null,
+    "compute_input_seq_cache": false,
+    "text_cleaner": null,
+    "enable_eos_bos_chars": false,
+    "test_sentences_file": "",
+    "phoneme_cache_path": null,
+    "characters": null,
+    "add_blank": false,
+    "batch_group_size": 48,
+    "loss_masking": null,
+    "min_audio_len": 1,
+    "max_audio_len": Infinity,
+    "min_text_len": 1,
+    "max_text_len": Infinity,
+    "compute_f0": false,
+    "compute_energy": false,
+    "compute_linear_spec": false,
+    "precompute_num_workers": 0,
+    "start_by_longest": false,
+    "shuffle": false,
+    "drop_last": false,
+    "datasets": [
+        {
+            "formatter": "",
+            "dataset_name": "",
+            "path": "",
+            "meta_file_train": "",
+            "ignored_speakers": null,
+            "language": "",
+            "phonemizer": "",
+            "meta_file_val": "",
+            "meta_file_attn_mask": ""
+        }
+    ],
+    "test_sentences": [
+        {
+            "text": "Ina kwana. Me kuke so mu yi yau?",
+            "speaker_wav": [
+                "/workspace/mtn-tts-tests/xtts-v2/dataset/references/hausa_fe_waxal_nlp_3.wav"
+            ],
+            "language": "ha"
+        },
+        {
+            "text": "Za ku iya taimaka mini da saita aikace aikacen katin sim?",
+            "speaker_wav": [
+                "/workspace/mtn-tts-tests/xtts-v2/dataset/references/hausa_fe_waxal_nlp_3.wav"
+            ],
+            "language": "ha"
+        }
+    ],
+    "eval_split_max_size": 256,
+    "eval_split_size": 0.01,
+    "use_speaker_weighted_sampler": false,
+    "speaker_weighted_sampler_alpha": 1.0,
+    "use_language_weighted_sampler": false,
+    "language_weighted_sampler_alpha": 1.0,
+    "use_length_weighted_sampler": false,
+    "length_weighted_sampler_alpha": 1.0,
+    "model_dir": null,
+    "languages": [
+        "en",
+        "es",
+        "fr",
+        "de",
+        "it",
+        "pt",
+        "pl",
+        "tr",
+        "ru",
+        "nl",
+        "cs",
+        "ar",
+        "zh-cn",
+        "hu",
+        "ko",
+        "ja",
+        "hi",
+        "ha"
+    ],
+    "temperature": 0.85,
+    "length_penalty": 1.0,
+    "repetition_penalty": 2.0,
+    "top_k": 50,
+    "top_p": 0.85,
+    "num_gpt_outputs": 1,
+    "gpt_cond_len": 12,
+    "gpt_cond_chunk_len": 4,
+    "max_ref_len": 10,
+    "sound_norm_refs": false,
+    "optimizer_wd_only_on_weights": true,
+    "weighted_loss_attrs": {},
+    "weighted_loss_multipliers": {},
+    "github_branch": "* main"
+}

env_config.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Load KEY=VALUE settings from config.env (project root).
+
+CLI flags always win over config.env values.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+DEFAULT_ENV_PATH = ROOT / "config.env"
+
+# Always take these from config.env so a broken shell mirror/token cannot win.
+_CONFIG_FORCE_KEYS = frozenset(
+    {
+        "HF_ENDPOINT",
+        "HF_TOKEN",
+        "HUGGINGFACE_ACCESS_TOKEN",
+        "HUGGING_FACE_HUB_TOKEN",
+        "HUGGINGFACE_TOKEN",
+        "HF_HUB_DOWNLOAD_TIMEOUT",
+        "HF_HUB_ETAG_TIMEOUT",
+        "HF_DOWNLOAD_RETRIES",
+    }
+)
+
+
+def load_config_env(path: Path | None = None, *, override: bool = False) -> Path | None:
+    """Parse config.env into os.environ.
+
+    Returns the path loaded, or None if missing.
+    Does not override existing environment variables unless override=True,
+    except for `_CONFIG_FORCE_KEYS` (HF endpoint/token/timeouts).
+    """
+    env_path = (path or DEFAULT_ENV_PATH).resolve()
+    if not env_path.is_file():
+        return None
+
+    for raw in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if not key:
+            continue
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        # Skip blank assignments (e.g. FOO=) so they don't poison Hub clients
+        if value == "":
+            continue
+        if override or key not in os.environ or key in _CONFIG_FORCE_KEYS:
+            os.environ[key] = value
+    return env_path
+
+
+def env_str(name: str, default: str | None = None) -> str | None:
+    v = os.getenv(name)
+    if v is None or v == "":
+        return default
+    return v
+
+
+def env_int(name: str, default: int) -> int:
+    v = os.getenv(name)
+    if v is None or v == "":
+        return default
+    return int(v)
+
+
+def env_float(name: str, default: float) -> float:
+    v = os.getenv(name)
+    if v is None or v == "":
+        return default
+    return float(v)
+
+
+def env_path(name: str, default: str | Path) -> Path:
+    v = os.getenv(name)
+    return Path(v) if v else Path(default)
+
+
+def env_list(name: str, default: list[str] | None = None) -> list[str]:
+    """Split a config value into a list (whitespace or comma separated)."""
+    v = os.getenv(name)
+    if v is None or v.strip() == "":
+        return list(default or [])
+    normalized = v.replace(",", " ")
+    parts = shlex.split(normalized)
+    return [p for p in parts if p]
+
+
+def ensure_config_loaded(path: Path | None = None) -> None:
+    loaded = load_config_env(path)
+    if loaded:
+        print(f"[config] loaded {loaded}")
+    else:
+        example = ROOT / "config.env.example"
+        print(
+            f"[config] no config.env found"
+            + (f" (copy from {example.name})" if example.is_file() else "")
+        )
+    apply_hf_token()
+
+
+def _sync_hf_hub_endpoint(endpoint: str) -> None:
+    """Keep huggingface_hub / datasets in sync if they were already imported."""
+    endpoint = endpoint.rstrip("/")
+    try:
+        import huggingface_hub.constants as hub_constants
+
+        hub_constants.ENDPOINT = endpoint
+        hub_constants.HUGGINGFACE_CO_URL_TEMPLATE = endpoint + "/{repo_id}/resolve/{revision}/{filename}"
+    except Exception:
+        pass
+    try:
+        import datasets.config as ds_config
+
+        ds_config.HF_ENDPOINT = endpoint
+        ds_config.HUB_DATASETS_URL = endpoint + "/datasets/{repo_id}/resolve/{revision}/{path}"
+    except Exception:
+        pass
+
+
+def apply_hf_token() -> None:
+    """Normalize HF token aliases and sync Hub endpoint.
+
+    HF_ENDPOINT from config.env already wins over the shell via
+    `_CONFIG_FORCE_KEYS` — no need to `unset HF_ENDPOINT` before runs.
+    """
+    endpoint = (os.environ.get("HF_ENDPOINT") or "").strip().rstrip("/")
+    if endpoint and not endpoint.startswith(("http://", "https://")):
+        del os.environ["HF_ENDPOINT"]
+        endpoint = ""
+    if not endpoint:
+        endpoint = "https://huggingface.co"
+        os.environ["HF_ENDPOINT"] = endpoint
+
+    _sync_hf_hub_endpoint(endpoint)
+    print(f"[config] HF_ENDPOINT={endpoint}")
+
+    # Longer timeouts help IncompleteRead on slow/unstable links
+    for key, default in (
+        ("HF_HUB_DOWNLOAD_TIMEOUT", "120"),
+        ("HF_HUB_ETAG_TIMEOUT", "60"),
+        ("HF_DOWNLOAD_RETRIES", "8"),
+    ):
+        val = env_str(key, default)
+        if val:
+            os.environ[key] = val
+
+    token = (
+        env_str("HF_TOKEN")
+        or env_str("HUGGINGFACE_ACCESS_TOKEN")
+        or env_str("HUGGING_FACE_HUB_TOKEN")
+        or env_str("HUGGINGFACE_TOKEN")
+    )
+    if not token:
+        print("[config] HF token not set (optional for public repos)")
+        return
+
+    os.environ["HF_TOKEN"] = token
+    os.environ["HUGGING_FACE_HUB_TOKEN"] = token
+    if not os.getenv("HUGGINGFACE_ACCESS_TOKEN"):
+        os.environ["HUGGINGFACE_ACCESS_TOKEN"] = token
+
+    print(f"[config] HF token loaded ({token[:6]}…{token[-4:] if len(token) > 10 else '****'})")
+
+    try:
+        from huggingface_hub import login
+
+        login(token=token, add_to_git_credential=False)
+    except Exception as e:
+        print(f"[config] huggingface_hub.login skipped: {e}")

infer.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Inference with a fine-tuned XTTS-v2 checkpoint.
+
+Defaults (from config.env):
+  python infer.py
+    -> synthesizes every line in SAMPLES_FILE for SPEAKER_REF
+
+Examples:
+  python infer.py
+  python infer.py --samples samples.txt --all-speakers
+  python infer.py --text "Ina kwana." --speaker-wav dataset/references/hausa_fe_waxal_nlp_3.wav
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+import torch
+import torchaudio
+from TTS.tts.configs.xtts_config import XttsConfig
+from TTS.tts.models.xtts import Xtts
+
+from env_config import (
+    ensure_config_loaded,
+    env_float,
+    env_int,
+    env_list,
+    env_path,
+    env_str,
+)
+from xtts_hausa_patch import apply_xtts_hausa_patches
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    v = env_str(name)
+    if v is None or v == "":
+        return default
+    return v.lower() in {"1", "true", "yes", "y", "on"}
+
+
+def _find_latest_run(training_root: Path) -> Path:
+    runs = sorted(
+        [p for p in training_root.glob("*") if p.is_dir()],
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    if not runs:
+        raise SystemExit(f"No training runs found under {training_root}")
+    return runs[0]
+
+
+def _load_samples(path: Path) -> list[str]:
+    lines = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        text = raw.strip()
+        if text and not text.startswith("#"):
+            lines.append(text)
+    if not lines:
+        raise SystemExit(f"No texts found in {path}")
+    return lines
+
+
+def _safe_stem(text: str, idx: int) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "_", text.lower()).strip("_")
+    slug = (slug[:40] or "utt").rstrip("_")
+    return f"{idx:02d}_{slug}"
+
+
+def _resolve_speaker_refs(
+    speaker_wav: Path | None,
+    all_speakers: bool,
+    dataset_dir: Path,
+) -> list[tuple[str, Path]]:
+    """Return list of (speaker_label, wav_path)."""
+    if all_speakers:
+        ids = env_list("SPEAKER_IDS")
+        refs_dir = dataset_dir / "references"
+        pairs: list[tuple[str, Path]] = []
+        for spk in ids:
+            p = refs_dir / f"{spk}.wav"
+            if not p.is_file():
+                raise SystemExit(f"Missing reference for speaker {spk}: {p}")
+            pairs.append((spk, p))
+        if not pairs:
+            raise SystemExit("INFER_ALL_SPEAKERS/SPEAKER_IDS set but no references found")
+        return pairs
+
+    if speaker_wav is None:
+        raise SystemExit("Provide --speaker-wav or set SPEAKER_REF in config.env")
+    if not speaker_wav.is_file():
+        raise SystemExit(f"Speaker reference not found: {speaker_wav}")
+    label = speaker_wav.stem
+    return [(label, speaker_wav)]
+
+
+def _load_model(model_dir: Path, base_dir: Path) -> tuple[Xtts, Path]:
+    config_path = model_dir / "config.json"
+    if not config_path.is_file():
+        candidates = list(model_dir.rglob("config.json"))
+        if not candidates:
+            raise SystemExit(f"No config.json under {model_dir}")
+        config_path = candidates[0]
+        model_dir = config_path.parent
+
+    ckpt = None
+    for name in ("best_model.pth", "model.pth"):
+        p = model_dir / name
+        if p.is_file():
+            ckpt = p
+            break
+    if ckpt is None:
+        pths = sorted(model_dir.glob("*.pth"), key=lambda p: p.stat().st_mtime, reverse=True)
+        if not pths:
+            raise SystemExit(f"No .pth checkpoint in {model_dir}")
+        ckpt = pths[0]
+
+    vocab = model_dir / "vocab.json"
+    if not vocab.is_file():
+        vocab = base_dir / "vocab.json"
+
+    print(f"Loading config={config_path}")
+    print(f"Loading checkpoint={ckpt}")
+    print(f"Using vocab={vocab}")
+
+    config = XttsConfig()
+    config.load_json(str(config_path))
+    model = Xtts.init_from_config(config)
+    model.load_checkpoint(
+        config,
+        checkpoint_path=str(ckpt),
+        vocab_path=str(vocab),
+        eval=True,
+        use_deepspeed=False,
+    )
+    if torch.cuda.is_available():
+        model.cuda()
+    return model, model_dir
+
+
+def _synthesize(
+    model: Xtts,
+    text: str,
+    language: str,
+    speaker_wav: Path,
+    args: argparse.Namespace,
+) -> torch.Tensor:
+    gpt_cond_latent, speaker_embedding = model.get_conditioning_latents(
+        audio_path=str(speaker_wav.resolve()),
+        gpt_cond_len=model.config.gpt_cond_len,
+        max_ref_length=model.config.max_ref_len,
+        sound_norm_refs=model.config.sound_norm_refs,
+    )
+    out = model.inference(
+        text=text,
+        language=language,
+        gpt_cond_latent=gpt_cond_latent,
+        speaker_embedding=speaker_embedding,
+        temperature=args.temperature,
+        length_penalty=args.length_penalty,
+        repetition_penalty=args.repetition_penalty,
+        top_k=args.top_k,
+        top_p=args.top_p,
+    )
+    return torch.tensor(out["wav"]).unsqueeze(0)
+
+
+def main() -> None:
+    ensure_config_loaded()
+    apply_xtts_hausa_patches()
+
+    speaker_default = env_str("SPEAKER_REF")
+    text_default = env_str("INFER_TEXT")
+    samples_default = env_str("SAMPLES_FILE", "samples.txt")
+
+    ap = argparse.ArgumentParser(description="XTTS-v2 Hausa inference")
+    ap.add_argument(
+        "--text",
+        default=None,
+        help="Single utterance (overrides samples file)",
+    )
+    ap.add_argument(
+        "--samples",
+        type=Path,
+        default=None,
+        help="Text file, one utterance per line (default: SAMPLES_FILE from config.env)",
+    )
+    ap.add_argument(
+        "--speaker-wav",
+        type=Path,
+        default=Path(speaker_default) if speaker_default else None,
+        help="Reference WAV (or set SPEAKER_REF in config.env)",
+    )
+    ap.add_argument(
+        "--all-speakers",
+        action="store_true",
+        default=_env_bool("INFER_ALL_SPEAKERS", False),
+        help="Synthesize for every SPEAKER_IDS reference under dataset/references/",
+    )
+    ap.add_argument("--language", default=env_str("LANGUAGE", "ha"))
+    ap.add_argument("--model-dir", type=Path, default=None)
+    ap.add_argument(
+        "--base-model-dir",
+        type=Path,
+        default=env_path("BASE_MODEL_DIR", "checkpoints/XTTS_v2.0_original_model_files"),
+    )
+    ap.add_argument(
+        "--out",
+        type=Path,
+        default=env_path("INFER_OUT", "outputs/out.wav"),
+        help="Output path for single --text mode",
+    )
+    ap.add_argument(
+        "--out-dir",
+        type=Path,
+        default=env_path("INFER_OUT_DIR", "outputs/samples"),
+        help="Output directory for samples-file mode",
+    )
+    ap.add_argument("--temperature", type=float, default=env_float("TEMPERATURE", 0.7))
+    ap.add_argument("--length-penalty", type=float, default=env_float("LENGTH_PENALTY", 1.0))
+    ap.add_argument("--repetition-penalty", type=float, default=env_float("REPETITION_PENALTY", 5.0))
+    ap.add_argument("--top-k", type=int, default=env_int("TOP_K", 50))
+    ap.add_argument("--top-p", type=float, default=env_float("TOP_P", 0.85))
+    args = ap.parse_args()
+
+    # Resolve texts: explicit --text > INFER_TEXT (only if --samples not passed) > samples file
+    texts: list[str]
+    batch_mode: bool
+    if args.text:
+        texts = [args.text]
+        batch_mode = False
+    elif args.samples is not None:
+        texts = _load_samples(args.samples)
+        batch_mode = True
+    elif text_default:
+        texts = [text_default]
+        batch_mode = False
+    else:
+        samples_path = Path(samples_default) if samples_default else Path("samples.txt")
+        texts = _load_samples(samples_path)
+        batch_mode = True
+        print(f"[infer] using samples file: {samples_path.resolve()}")
+
+    dataset_dir = env_path("DATASET_DIR", "dataset")
+    speakers = _resolve_speaker_refs(args.speaker_wav, args.all_speakers, dataset_dir)
+
+    base_dir = args.base_model_dir.resolve()
+    if args.model_dir is None:
+        model_dir = _find_latest_run(Path("checkpoints/run/training").resolve())
+    else:
+        model_dir = args.model_dir.resolve()
+
+    model, _ = _load_model(model_dir, base_dir)
+
+    if batch_mode:
+        out_dir = args.out_dir.resolve()
+        out_dir.mkdir(parents=True, exist_ok=True)
+        for spk_label, spk_wav in speakers:
+            spk_dir = out_dir / spk_label if len(speakers) > 1 else out_dir
+            spk_dir.mkdir(parents=True, exist_ok=True)
+            print(f"\n=== speaker={spk_label} ref={spk_wav} ===")
+            for i, text in enumerate(texts, start=1):
+                out_path = spk_dir / f"{_safe_stem(text, i)}.wav"
+                print(f"[{i}/{len(texts)}] {text[:80]}...")
+                wav = _synthesize(model, text, args.language, spk_wav, args)
+                torchaudio.save(str(out_path), wav, 24000)
+                print(f"  -> {out_path}")
+        print(f"\nDone. Wrote {len(texts) * len(speakers)} files under {out_dir}")
+    else:
+        spk_label, spk_wav = speakers[0]
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        wav = _synthesize(model, texts[0], args.language, spk_wav, args)
+        torchaudio.save(str(args.out), wav, 24000)
+        print(f"Wrote {args.out} (speaker={spk_label})")
+
+
+if __name__ == "__main__":
+    main()

references/hausa_fe_naijavoices_O0456.wav

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

references/hausa_fe_waxal_nlp_3.wav

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

references/hausa_fe_waxal_nlp_5.wav

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

requirements.txt

@@ -0,0 +1,15 @@
+# Maintained Coqui TTS fork (includes XTTS GPT fine-tuning trainer)
+coqui-tts[all,codec]>=0.27.0
+torch
+torchaudio
+torchcodec
+transformers>=4.40,<5.0
+datasets>=2.19.0
+soundfile
+librosa
+numpy
+pandas
+tokenizers
+huggingface_hub
+tqdm
+tensorboard

samples.txt

@@ -0,0 +1,5 @@
+za ku iya taimaka min da sa ita aikace aikacen katin sim?
+na san game da katin sim. na iya taimaka maka samun bayyane game da yadda za a iya amfani da shi.menene kuma kake buƙata game da katin sim?
+to, na sanar da kai cewa ba zan iya taimaka maka ba, amma zan iya bayar da shawara, ko taimakon da zai taimake ka. menene kuma bayanan da kake nema?
+kin kaɗ ɗina ba ya kunna ko da bayan saka menene matsalar?
+shin akwai hanyar yin canjin sim na wani daga wayata?

xtts_hausa_patch.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Runtime patches required for Hausa (and other non-native XTTS languages).
+
+1) VoiceBpeTokenizer.preprocess_text raises NotImplementedError for `ha`.
+2) After vocab extension, text embeddings grow; load_checkpoint must pad
+   pretrained weights instead of skipping the whole embedding matrix.
+3) Xtts.synthesize asserts language ∈ config.languages — GPTTrainerConfig
+   defaults omit langs added only in on-disk config.json (e.g. ha).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import torch
+from TTS.tts.layers.xtts.tokenizer import VoiceBpeTokenizer
+from TTS.tts.layers.xtts.trainer.gpt_trainer import GPTTrainer
+from TTS.tts.models.xtts import Xtts
+from TTS.tts.utils.text.cleaners import basic_cleaners, collapse_whitespace, lowercase
+
+logger = logging.getLogger("xtts_hausa_patch")
+_APPLIED = False
+
+
+def _hausa_preprocess_text(self, txt, lang):
+    lang = (lang or "").split("-")[0]
+    supported = {"ar", "cs", "de", "en", "es", "fr", "hi", "hu", "it", "nl", "pl", "pt", "ru", "tr", "zh", "ko"}
+    if lang in supported:
+        from TTS.tts.layers.xtts.tokenizer import multilingual_cleaners, chinese_transliterate
+
+        txt = multilingual_cleaners(txt, lang)
+        if lang == "zh":
+            txt = chinese_transliterate(txt)
+        if lang == "ko":
+            from ko_speech_tools import hangul_romanize
+
+            txt = hangul_romanize(txt)
+        return txt
+    if lang == "ja":
+        from TTS.tts.layers.xtts.tokenizer import japanese_cleaners
+
+        return japanese_cleaners(txt, self.katsu)
+
+    # New / unsupported languages (Hausa, etc.): keep Latin orthography, light clean.
+    txt = txt.replace('"', "")
+    txt = lowercase(txt)
+    txt = basic_cleaners(txt)
+    txt = collapse_whitespace(txt)
+    return txt
+
+
+def _pad_text_layers(state: dict, model) -> dict:
+    """Pad gpt text_embedding / text_head when vocab was extended."""
+    emb_key = None
+    for key in ("gpt.text_embedding.weight", "text_embedding.weight"):
+        if key in state:
+            emb_key = key
+            break
+    if emb_key is None or model.gpt is None:
+        return state
+
+    ckpt_emb = state[emb_key]
+    model_emb = model.gpt.text_embedding.weight
+    if ckpt_emb.shape == model_emb.shape:
+        return state
+
+    if ckpt_emb.shape[0] > model_emb.shape[0]:
+        logger.warning(
+            "Checkpoint text vocab (%d) larger than model (%d); truncating.",
+            ckpt_emb.shape[0],
+            model_emb.shape[0],
+        )
+        state[emb_key] = ckpt_emb[: model_emb.shape[0]].clone()
+        return state
+
+    num_new = model_emb.shape[0] - ckpt_emb.shape[0]
+    logger.info("Padding text embedding with %d new token rows for extended vocab.", num_new)
+
+    new_rows = torch.randn(num_new, ckpt_emb.shape[1], dtype=ckpt_emb.dtype)
+    # Keep old EOS/special last-row convention used by Coqui GPTTrainer.
+    start_token_row = ckpt_emb[-1, :].clone()
+    padded = torch.cat([ckpt_emb, new_rows], dim=0)
+    padded[-1, :] = start_token_row
+    state[emb_key] = padded
+
+    head_w_key = "gpt.text_head.weight" if "gpt.text_head.weight" in state else "text_head.weight"
+    head_b_key = "gpt.text_head.bias" if "gpt.text_head.bias" in state else "text_head.bias"
+    if head_w_key in state:
+        tw = state[head_w_key]
+        start = tw[-1, :].clone()
+        new_w = torch.randn(num_new, tw.shape[1], dtype=tw.dtype)
+        tw = torch.cat([tw, new_w], dim=0)
+        tw[-1, :] = start
+        state[head_w_key] = tw
+    if head_b_key in state:
+        tb = state[head_b_key]
+        start_b = tb[-1].clone()
+        new_b = torch.zeros(num_new, dtype=tb.dtype)
+        tb = torch.cat([tb, new_b], dim=0)
+        tb[-1] = start_b
+        state[head_b_key] = tb
+
+    return state
+
+
+_ORIG_LOAD_CHECKPOINT = GPTTrainer.load_checkpoint
+_ORIG_SYNTHESIZE = Xtts.synthesize
+
+
+def _ensure_language(config, language: str | None) -> None:
+    """Allow fine-tune languages that exist in vocab but not in dataclass defaults."""
+    if not language or not hasattr(config, "languages"):
+        return
+    lang = "zh-cn" if language == "zh" else language
+    langs = list(config.languages or [])
+    if lang not in langs:
+        langs.append(lang)
+        config.languages = langs
+        logger.info("Registered language '%s' on XTTS config for synthesize/inference.", lang)
+
+
+def _patched_synthesize(self, text, config=None, *, speaker_wav=None, language=None, **kwargs):
+    _ensure_language(self.config, language)
+    return _ORIG_SYNTHESIZE(
+        self, text, config, speaker_wav=speaker_wav, language=language, **kwargs
+    )
+
+
+def _patched_load_checkpoint(
+    self,
+    config,
+    checkpoint_path,
+    *,
+    eval=False,
+    strict=True,
+    cache_storage="/tmp/tts_cache",
+    target_protocol="s3",
+    target_options=None,
+):
+    if target_options is None:
+        target_options = {"anon": True}
+    state = self.xtts.get_compatible_checkpoint_state_dict(checkpoint_path)
+    state = _pad_text_layers(state, self.xtts)
+    # After padding, shapes match — prefer strict load of GPT weights when possible.
+    self.xtts.load_state_dict(state, strict=False)
+    if eval:
+        self.xtts.gpt.init_gpt_for_inference(kv_cache=self.args.kv_cache, use_deepspeed=False)
+        self.eval()
+
+
+def apply_xtts_hausa_patches() -> None:
+    global _APPLIED
+    if _APPLIED:
+        return
+    VoiceBpeTokenizer.preprocess_text = _hausa_preprocess_text
+    GPTTrainer.load_checkpoint = _patched_load_checkpoint
+    Xtts.synthesize = _patched_synthesize
+    _APPLIED = True
+    logger.info("Applied XTTS Hausa patches (tokenizer + embedding pad + languages).")
+    print("[patch] XTTS Hausa tokenizer + embedding-pad + language patches applied")