Update README.md

README.md

@@ -16,42 +16,58 @@ tags:
 pipeline_tag: text-to-speech
 ---
 
-# ZipVoice-CA:  Fast and High-Quality Zero-Shot Text-to-Speech with Flow Matching (now in Catalan!)
+# ZipVoice-CA: Catalan Zero-Shot Text-to-Speech with ZipVoice
 
-This repository contains the checkpoint of the fine-tuned ZipVoice-CA model, able to synthesise speech in catalan with great quality. Its metrics follow below.
-For more information regarding the training and evaluation of the model please refer to its repository on https://github.com/ErikUPV/ZipVoice-CA.
-Please also visit the repository of the original [ZipVoice](https://github.com/k2-fsa/ZipVoice) model.
+Catalan fine-tune of [ZipVoice](https://github.com/k2-fsa/ZipVoice), a fast zero-shot text-to-speech model based on flow matching.
 
-To get a feel of the model, click [here](https://erikupv.github.io/zipvoice-samples/) to listen to some samples.
+<p align="center">
+  <a href="https://erikupv.github.io/zipvoice-samples/">
+    <img src="https://img.shields.io/badge/🔊%20Listen-Samples-green" alt="Listen to samples">
+  </a>
+  <a href="https://github.com/ErikUPV/ZipVoice-CA">
+    <img src="https://img.shields.io/badge/GitHub-ZipVoice--CA-orange?logo=github&logoColor=white" alt="GitHub repository">
+  </a>
+  <a href="https://github.com/k2-fsa/ZipVoice">
+    <img src="https://img.shields.io/badge/Base%20Model-ZipVoice-blue" alt="Base ZipVoice repository">
+  </a>
+</p>
+This repository contains the fine-tuned ZipVoice-CA checkpoint for Catalan speech synthesis. For the full training, preprocessing, inference, and evaluation recipe, see the [GitHub repository](https://github.com/ErikUPV/ZipVoice-CA).
+
+The metrics below are intended as indicative benchmarks under this repository's evaluation setup, not as definitive state-of-the-art claims.
+
+---
 
 ## Performance Metrics
 
-| Dataset | WER (%) ↓ | CER (%) ↓ | SIM-o ↑ | UTMOS ↑ |
-| :--- | :---: | :---: | :---: | :---: |
-| **Common Voice 17** | 10.96 | 3.00 | 0.68 | 3.17 |
-| **Festcat** | 7.31 | 2.56 | 0.65 | 3.46 |
-| **LaFrescat** | 7.61 | 2.56 | 0.67 | 3.54 |
+| Dataset         | WER (%) ↓ | CER (%) ↓ | SIM-o ↑ | UTMOS ↑ |
+| --------------- | --------: | --------: | ------: | ------: |
+| Common Voice 17 |     10.96 |      3.00 |    0.68 |    3.17 |
+| FestCat         |      7.31 |      2.56 |    0.65 |    3.46 |
+| LaFrescat       |      7.61 |      2.56 |    0.67 |    3.54 |
+
+Evaluation uses generated samples from the ZipVoice-CA recipe with `guidance_scale=1.0` and `num_step=25`.
 
 ---
 
 ## Installation
 
-### 1. Clone the repository
+### 1. Clone the recipe repository
+
 ```bash
-git clone https://github.com/erikupv/zipvoice-ca
-cd zipvoice-ca
+git clone https://github.com/ErikUPV/ZipVoice-CA.git
+cd ZipVoice-CA
 ```
 
-### 2. Environment Setup
-We recommend using **Conda** to manage your dependencies and ensure a clean environment:
+### 2. Create the environment
+
 ```bash
 conda create -n ZipVoice python=3.11
 conda activate ZipVoice
 pip install -r requirements_zipvoice.txt
 ```
 
-### 3. Download the Catalan Model
-Use the Hugging Face CLI to download the fine-tuned checkpoint directly into your local models directory:
+### 3. Download the Catalan checkpoint
+
 ```bash
 # pip install huggingface_hub
 huggingface-cli download \
@@ -64,41 +80,72 @@ huggingface-cli download \
 
 ## Inference
 
-To generate speech from a test.tsv file using the Catalan model, use the command below.
+### Batch inference from a `test.tsv` file
 
 ```bash
 python3 -m zipvoice.bin.infer_zipvoice \
-    --model-name zipvoice \
-    --model-dir ./models \
-    --checkpoint-name zipvoice_ca.pt \
-    --tokenizer "espeak" \
-    --lang "ca" \
-    --test-list data_cat/raw/test.tsv \
-    --res-dir results/ \
-    --guidance-scale 1.0 \
-    --num-step 16
+  --model-name zipvoice \
+  --model-dir ./models \
+  --checkpoint-name zipvoice_ca.pt \
+  --tokenizer espeak \
+  --lang ca \
+  --test-list data_cat/raw/test.tsv \
+  --res-dir results/ \
+  --guidance-scale 1.0 \
+  --num-step 25
 ```
 
-For single file inference
+### Single-sample inference
 
 ```bash
 python3 -m zipvoice.bin.infer_zipvoice \
-    --model-name zipvoice \
-    --prompt-wav prompt.wav \
-    --prompt-text "I am the transcription of the prompt wav." \
-    --text "I am the text to be synthesized." \
-    --res-wav-path result.wav
-    --model-dir ./models \
-    --checkpoint-name zipvoice_ca.pt \
-    --tokenizer "espeak" \
-    --lang "ca" \
-    --guidance-scale 1.0 \
-    --num-step 16
+  --model-name zipvoice \
+  --prompt-wav prompt.wav \
+  --prompt-text "I am the transcription of the prompt wav." \
+  --text "I am the text to be synthesized." \
+  --res-wav-path result.wav \
+  --model-dir ./models \
+  --checkpoint-name zipvoice_ca.pt \
+  --tokenizer espeak \
+  --lang ca \
+  --guidance-scale 1.0 \
+  --num-step 25
 ```
+
+The prompt audio should contain the reference speaker voice, and `--prompt-text` should match the transcription of that prompt audio.
+
+---
+
+## Evaluation Setup
+
+The reported metrics are computed on generated samples from three Catalan evaluation sources:
+
+* held-out Common Voice 17 Catalan samples,
+* FestCat prompts,
+* LaFrescat prompts.
+
+Metrics:
+
+* **WER / CER**: ASR-based intelligibility metrics.
+* **SIM-o**: speaker similarity between prompt and generated speech.
+* **UTMOS**: automatic MOS-style naturalness estimate.
+
+---
+
+## Limitations
+
+This model is intended for Catalan text-to-speech research and experimentation. Quality may vary depending on prompt quality, prompt duration, speaker characteristics, text normalization, and out-of-domain inputs.
+
+As with any zero-shot TTS model, users should avoid generating speech that impersonates real people without consent.
+
 ---
 
 ## Acknowledgments
-This work is a fine-tuned version of the [ZipVoice](https://github.com/k2-fsa/ZipVoice) project.
+
+This model is a fine-tuned version of [ZipVoice](https://github.com/k2-fsa/ZipVoice), using the pretrained checkpoint released by the original authors.
+
+---
 
 ## License
-This project is licensed under the **Apache-2.0 License**.
+
+This model is released under the Apache-2.0 License.