Create README.md

# Basque Unit-HiFiGAN Vocoder (Voices: Mariana & Alex)
## Model Summary

This repository provides a Unit-HiFiGAN vocoder trained to synthesize high-fidelity Basque speech from discrete HuBERT-derived unit sequences. The model supports two speaker identities, Mariana and Alex, using learned speaker-conditioning embeddings. It is compatible with HuBERT features extracted from layer 9 and clustered using a KMeans (k=1000) quantizer.

The vocoder is designed for unit-based text-to-speech, voice conversion, and speech synthesis research in Basque. It reconstructs waveform audio from sequences of discrete unit IDs and optional speaker embeddings.

## Key Features

Voices: Mariana and Alex

Architecture: Unit-HiFiGAN (SpeechBrain implementation)

Input: Discrete HuBERT units (1D sequence of cluster IDs)

Output: 16 kHz Basque speech signal

Speaker conditioning: Single-speaker or multi-speaker inference via speaker embeddings

Compatible encoders: Basque-finetuned HuBERT (layer 9 hidden states → KMeans)

Use cases: Basque TTS research, unit-based synthesis, voice conversion, controllable speaker identity

## How to Use

Below is a minimal inference example that replicates the expected workflow:

```
import torch
import torchaudio
import joblib
import numpy as np
from transformers import Wav2Vec2Processor, HubertModel
from speechbrain.inference.vocoders import UnitHIFIGAN
from huggingface_hub import hf_hub_download

DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
SR = 16000

# 1. Load HuBERT
processor = Wav2Vec2Processor.from_pretrained("your-hubert-repo")
hubert = HubertModel.from_pretrained("your-hubert-repo").to(DEVICE).eval()

# 2. Load KMeans
kmeans_path = hf_hub_download("your-hubert-repo", "kmeans/basque_hubert_k1000_L9.pt")
kmeans = joblib.load(kmeans_path)

# 3. Load vocoder
vocoder = UnitHIFIGAN.from_hparams(
source="your-vocoder-repo",
run_opts={"device": DEVICE}
).eval()

# 4. Load audio
wav, sr = torchaudio.load("example.wav")
wav = torchaudio.functional.resample(wav, sr, SR)

# 5. HuBERT → units
inputs = processor(wav, sampling_rate=SR, return_tensors="pt")
inputs["input_values"] = inputs["input_values"].to(DEVICE)

with torch.no_grad():
hidden = hubert(**inputs, output_hidden_states=True).hidden_states[9]

features = hidden.squeeze(0).cpu().numpy()
unit_ids = kmeans.predict(features)
units = torch.LongTensor(unit_ids).unsqueeze(0).unsqueeze(-1).to(DEVICE)

# 6. Optional speaker embedding (Mariana or Alex)
# Example: load Mariana's embedding
spk_emb = torch.FloatTensor(
np.load("speaker_embeddings/mariana.npy")
).unsqueeze(0).to(DEVICE)

# 7. Vocoder decode
with torch.no_grad():
wav_out = vocoder.decode_batch(units, spk_emb=spk_emb)

torchaudio.save("output_mariana.wav", wav_out.cpu(), SR)
print("Saved: output_mariana.wav")
```

README.md

@@ -0,0 +1,81 @@
+# Basque Unit-HiFiGAN Vocoder (Voices: Mariana & Alex)
+## Model Summary
+
+This repository provides a Unit-HiFiGAN vocoder trained to synthesize high-fidelity Basque speech from discrete HuBERT-derived unit sequences. The model supports two speaker identities, Mariana and Alex, using learned speaker-conditioning embeddings. It is compatible with HuBERT features extracted from layer 9 and clustered using a KMeans (k=1000) quantizer.
+
+The vocoder is designed for unit-based text-to-speech, voice conversion, and speech synthesis research in Basque. It reconstructs waveform audio from sequences of discrete unit IDs and optional speaker embeddings.
+
+## Key Features
+
+Voices: Mariana and Alex
+
+Architecture: Unit-HiFiGAN (SpeechBrain implementation)
+
+Input: Discrete HuBERT units (1D sequence of cluster IDs)
+
+Output: 16 kHz Basque speech signal
+
+Speaker conditioning: Single-speaker or multi-speaker inference via speaker embeddings
+
+Compatible encoders: Basque-finetuned HuBERT (layer 9 hidden states → KMeans)
+
+Use cases: Basque TTS research, unit-based synthesis, voice conversion, controllable speaker identity
+
+## How to Use
+
+Below is a minimal inference example that replicates the expected workflow:
+
+```
+import torch
+import torchaudio
+import joblib
+import numpy as np
+from transformers import Wav2Vec2Processor, HubertModel
+from speechbrain.inference.vocoders import UnitHIFIGAN
+from huggingface_hub import hf_hub_download
+
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+SR = 16000
+
+# 1. Load HuBERT
+processor = Wav2Vec2Processor.from_pretrained("your-hubert-repo")
+hubert = HubertModel.from_pretrained("your-hubert-repo").to(DEVICE).eval()
+
+# 2. Load KMeans
+kmeans_path = hf_hub_download("your-hubert-repo", "kmeans/basque_hubert_k1000_L9.pt")
+kmeans = joblib.load(kmeans_path)
+
+# 3. Load vocoder
+vocoder = UnitHIFIGAN.from_hparams(
+    source="your-vocoder-repo",
+    run_opts={"device": DEVICE}
+).eval()
+
+# 4. Load audio
+wav, sr = torchaudio.load("example.wav")
+wav = torchaudio.functional.resample(wav, sr, SR)
+
+# 5. HuBERT → units
+inputs = processor(wav, sampling_rate=SR, return_tensors="pt")
+inputs["input_values"] = inputs["input_values"].to(DEVICE)
+
+with torch.no_grad():
+    hidden = hubert(**inputs, output_hidden_states=True).hidden_states[9]
+
+features = hidden.squeeze(0).cpu().numpy()
+unit_ids = kmeans.predict(features)
+units = torch.LongTensor(unit_ids).unsqueeze(0).unsqueeze(-1).to(DEVICE)
+
+# 6. Optional speaker embedding (Mariana or Alex)
+# Example: load Mariana's embedding
+spk_emb = torch.FloatTensor(
+    np.load("speaker_embeddings/mariana.npy")
+).unsqueeze(0).to(DEVICE)
+
+# 7. Vocoder decode
+with torch.no_grad():
+    wav_out = vocoder.decode_batch(units, spk_emb=spk_emb)
+
+torchaudio.save("output_mariana.wav", wav_out.cpu(), SR)
+print("Saved: output_mariana.wav")
+```