added description and "how to use" example

README.md

@@ -27,46 +27,85 @@ model-index:
       type: wer
       value: 5.408751772230669
 ---
+# Whisper Medium Spanish
 
-<!-- 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. -->
+## Model summary
 
-# Whisper Medium Spanish
+**Whisper Medium Spanish** is an automatic speech recognition (ASR) model for **Spanish (es)**, fine-tuned from [openai/whisper-medium] on the **Spanish subset of Mozilla Common Voice 13.0**. It achieves a **Word Error Rate (WER) of 5.4088%** on the evaluation split.
+
+This model offers higher accuracy than Whisper Small while remaining more efficient than Whisper Large variants, making it suitable for both batch and near real-time transcription of Spanish speech.
 
-This model is a fine-tuned version of [openai/whisper-medium](https://huggingface.co/openai/whisper-medium) on the mozilla-foundation/common_voice_13_0 es dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.1915
-- Wer: 5.4088
+---
 
 ## Model description
 
-More information needed
+* **Architecture:** Transformer-based encoder–decoder (Whisper Medium)  
+* **Base model:** openai/whisper-medium  
+* **Language:** Spanish (es)  
+* **Task:** Automatic Speech Recognition (ASR)  
+* **Output:** Text transcription in Spanish  
+* **Decoding:** Autoregressive sequence-to-sequence decoding  
+
+Medium-sized model balances accuracy and speed, handling conversational Spanish better than smaller models.
+
+---
+
+## Intended use
+
+### Primary use cases
+
+* Batch or streaming transcription of Spanish speech  
+* Research on Spanish ASR  
+* Applications requiring moderate-to-high transcription accuracy without full-large model compute  
+
+### Limitations
 
-## Intended uses & limitations
+* Accuracy may drop for:
+  * Noisy environments or overlapping speakers  
+  * Strong regional accents not well represented in Common Voice  
+  * Extremely fast or slurred speech  
 
-More information needed
+* Not intended for legal, medical, or other safety-critical transcription.
+
+---
 
 ## Training and evaluation data
 
-More information needed
+* **Dataset:** Mozilla Common Voice 13.0 (Spanish subset)  
+* **Data type:** Crowd-sourced read speech  
+* **Preprocessing:**  
+  * Audio resampled to 16 kHz  
+  * Text tokenized with Whisper tokenizer  
+  * Removal of invalid or corrupted samples  
+
+* **Evaluation metric:** Word Error Rate (WER) on held-out evaluation set  
+
+---
+
+## Evaluation results
+
+| Metric     | Value      |
+| ---------- | ---------- |
+| WER (eval) | **5.4088%** |
+
+---
 
 ## Training procedure
 
 ### Training hyperparameters
 
-The following hyperparameters were used during training:
-- learning_rate: 1e-05
-- train_batch_size: 64
-- eval_batch_size: 32
-- seed: 42
-- optimizer: Adam with betas=(0.9,0.999) and epsilon=1e-08
-- lr_scheduler_type: linear
-- lr_scheduler_warmup_steps: 500
-- training_steps: 10000
+* Learning rate: 1e-5  
+* Optimizer: Adam (β1=0.9, β2=0.999, ε=1e-8)  
+* LR scheduler: Linear  
+* Warmup steps: 500  
+* Training steps: 10000  
+* Train batch size: 64  
+* Eval batch size: 32  
+* Seed: 42  
 
-### Training results
+### Training results (summary)
 
-| Training Loss | Epoch | Step  | Validation Loss | Wer    |
+| Training Loss | Epoch | Step  | Validation Loss | WER    |
 |:-------------:|:-----:|:-----:|:---------------:|:------:|
 | 0.0917        | 2.0   | 1000  | 0.1944          | 6.8560 |
 | 0.0927        | 4.0   | 2000  | 0.1817          | 6.1439 |
@@ -79,27 +118,57 @@ The following hyperparameters were used during training:
 | 0.1297        | 18.02 | 9000  | 0.1831          | 5.6885 |
 | 0.0377        | 20.02 | 10000 | 0.1915          | 5.4088 |
 
+---
 
-### Framework versions
+## Framework versions
 
-- Transformers 4.33.0.dev0
-- Pytorch 2.0.1+cu117
-- Datasets 2.14.4
-- Tokenizers 0.13.3
+- Transformers 4.33.0.dev0  
+- PyTorch 2.0.1+cu117  
+- Datasets 2.14.4  
+- Tokenizers 0.13.3  
+
+---
+
+## Example usage
+
+```python
+from transformers import pipeline
+
+hf_model = "HiTZ/whisper-medium-es"  # replace with actual repo ID
+device = 0  # -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}
 }
 ```
 
@@ -107,9 +176,22 @@ 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.
+