Added description and "how to use" example

README.md

@@ -28,46 +28,112 @@ model-index:
       value: 5.971420405830237
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
-
 # Whisper Large-V3 Catalan
 
-This model is a fine-tuned version of [openai/whisper-large-v3](https://huggingface.co/openai/whisper-large-v3) on the mozilla-foundation/common_voice_13_0 ca dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.2783
-- Wer: 5.9714
+## Model summary
+
+**Whisper Large-V3 Catalan** is an automatic speech recognition (ASR) model for **Catalan** speech. It is fine-tuned from [openai/whisper-large-v3] on the Catalan portion of **Mozilla Common Voice 13.0**, achieving a **Word Error Rate (WER) of 5.97%** on the Common Voice test split.
+
+The model is intended for high-quality transcription of Catalan speech in a variety of accents and recording conditions, including read and semi-spontaneous speech.
+
+---
 
 ## Model description
 
-More information needed
+* **Architecture:** Transformer-based encoder–decoder (Whisper)
+* **Base model:** openai/whisper-large-v3
+* **Language:** Catalan (ca)
+* **Task:** Automatic Speech Recognition (ASR)
+* **Output:** Text transcription in Catalan
+* **Decoding:** Autoregressive sequence-to-sequence decoding
+
+This model leverages Whisper's multilingual pretraining and large-scale speech-text alignment, followed by supervised fine-tuning on Catalan speech data to improve language-specific accuracy.
+
+---
+
+## Intended use
+
+### Primary use cases
+
+* Transcription of Catalan audio recordings
+* Speech-to-text pipelines for media, education, and research
+* Accessibility tools (e.g., subtitles, captions)
+* Offline or batch ASR for Catalan datasets
 
-## Intended uses & limitations
+### Intended users
 
-More information needed
+* Researchers working on Catalan or low-resource ASR
+* Developers building Catalan speech applications
+* Institutions and companies requiring Catalan transcription
+
+### Out-of-scope use
+
+* Real-time or low-latency ASR without optimization
+* Speech translation (this model performs transcription only)
+* Safety-critical applications without additional validation
+
+---
+
+## Limitations and known issues
+
+* Performance may degrade on:
+
+  * Highly noisy audio
+  * Strong regional accents underrepresented in Common Voice
+  * Conversational or overlapping speech
+* The model may produce hallucinated text when audio quality is very poor or silent.
+* Biases present in the Common Voice dataset (e.g., demographic or accent imbalance) may be reflected in model outputs.
+
+Users are encouraged to evaluate the model on their own data before deployment.
+
+---
 
 ## Training and evaluation data
 
-More information needed
+### Training data
+
+* **Dataset:** Mozilla Common Voice 13.0 (Catalan subset)
+* **Data type:** Crowd-sourced, read speech
+* **Preprocessing:**
+
+  * Audio resampled to 16 kHz
+  * Text normalized using Whisper tokenizer
+  * Invalid or excessively long samples filtered
+
+### Evaluation data
+
+* **Dataset:** Common Voice 13.0 (Catalan test split)
+* **Metric:** Word Error Rate (WER)
+
+---
+
+## Evaluation results
+
+| Metric     | Value     |
+| ---------- | --------- |
+| WER (test) | **5.97%** |
+
+These results indicate strong performance compared to the base Whisper multilingual model on Catalan speech.
+
+---
 
 ## Training procedure
 
 ### Training hyperparameters
 
-The following hyperparameters were used during training:
-- learning_rate: 1e-05
-- train_batch_size: 32
-- eval_batch_size: 16
-- seed: 42
-- gradient_accumulation_steps: 2
-- total_train_batch_size: 64
-- optimizer: Adam with betas=(0.9,0.999) and epsilon=1e-08
-- lr_scheduler_type: linear
-- lr_scheduler_warmup_steps: 500
-- training_steps: 20000
-- mixed_precision_training: Native AMP
-
-### Training results
+* Learning rate: 1e-5
+* Optimizer: Adam (β1=0.9, β2=0.999, ε=1e-8)
+* LR scheduler: Linear
+* Warmup steps: 500
+* Training steps: 20,000
+* Train batch size: 32
+* Gradient accumulation steps: 2
+* Effective batch size: 64
+* Evaluation batch size: 16
+* Mixed precision: FP16 (Native AMP)
+* Seed: 42
+
+### Training results (summary)
 
 | Training Loss | Epoch | Step  | Validation Loss | Wer    |
 |:-------------:|:-----:|:-----:|:---------------:|:------:|
@@ -100,19 +166,48 @@ The following hyperparameters were used during training:
 - Datasets 2.16.1
 - Tokenizers 0.15.1
 
+---
+
+## How to use
+
+```python
+from transformers import pipeline
+
+hf_model = "HiTZ/whisper-large-v3-ca"
+device = 0 # set to -1 for CPU
+
+pipe = pipeline(
+    task="automatic-speech-recognition",
+    model=hf_model,
+    device=device 
+)
+
+result = pipe("audio.wav")
+print(result["text"])
+```
+
+---
+
+## Ethical considerations and risks
+
+* This model transcribes speech and may process personal data.
+* Users should ensure compliance with applicable data protection laws (e.g., GDPR).
+* The model should not be used for surveillance or non-consensual audio processing.
+
+---
+
 ## Citation
 
-If you use these models in your research, please cite:
+If you use this model in your research, please cite:
 
 ```bibtex
 @misc{dezuazo2025whisperlmimprovingasrmodels,
-      title={Whisper-LM: Improving ASR Models with Language Models for Low-Resource Languages}, 
-      author={Xabier de Zuazo and Eva Navas and Ibon Saratxaga and Inma Hernáez Rioja},
-      year={2025},
-      eprint={2503.23542},
-      archivePrefix={arXiv},
-      primaryClass={cs.CL},
-      url={https://arxiv.org/abs/2503.23542}, 
+  title={Whisper-LM: Improving ASR Models with Language Models for Low-Resource Languages},
+  author={Xabier de Zuazo and Eva Navas and Ibon Saratxaga and Inma Hernáez Rioja},
+  year={2025},
+  eprint={2503.23542},
+  archivePrefix={arXiv},
+  primaryClass={cs.CL}
 }
 ```
 
@@ -120,9 +215,21 @@ Please, check the related paper preprint in
 [arXiv:2503.23542](https://arxiv.org/abs/2503.23542)
 for more details.
 
-## Licensing
+---
+
+## License
 
 This model is available under the
 [Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0).
 You are free to use, modify, and distribute this model as long as you credit
-the original creators.
+the original creators.
+
+---
+
+## Contact and attribution
+
+* Fine-tuning and evaluation: HiTZ/Aholab - Basque Center for Language Technology
+* Base model: OpenAI Whisper
+* Dataset: Mozilla Common Voice
+
+For questions or issues, please open an issue in the model repository.