> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-fr/audio-et-voix/whisperx.md).

# WhisperX avec diarisation

WhisperX étend Whisper d'OpenAI avec trois améliorations cruciales : **horodatages au niveau des mots** via alignement forcé des phonèmes, **diarisation des locuteurs** en utilisant pyannote.audio, et **jusqu'à 70× la vitesse en temps réel** grâce à l'inférence par lots avec faster-whisper. C'est l'outil de référence pour les pipelines de transcription en production qui ont besoin d'un timing précis et d'une identification des locuteurs.

**GitHub :** [m-bain/whisperX](https://github.com/m-bain/whisperX) **PyPI :** [whisperx](https://pypi.org/project/whisperx/) **Licence :** BSD-4-Clause **Article :** [arxiv.org/abs/2303.00747](https://arxiv.org/abs/2303.00747)

## Principales caractéristiques

* **Horodatages au niveau des mots** — précision ±50 ms via alignement forcé wav2vec2 (vs ±500 ms dans Whisper vanilla)
* **Diarisation des locuteurs** — identifiez qui a dit quoi via pyannote.audio 3.1
* **Inférence par lots** — jusqu'à 70× la vitesse en temps réel sur RTX 4090
* **Pré-filtrage VAD** — Silero VAD supprime les silences avant la transcription
* **Tous les modèles Whisper** — tiny jusqu'à large-v3-turbo
* **Formats de sortie multiples** — JSON, SRT, VTT, TXT, TSV
* **Détection automatique de la langue** — ou forcez une langue spécifique pour un traitement plus rapide

## Exigences

| Composant | Minimum             | Recommandé               |
| --------- | ------------------- | ------------------------ |
| GPU       | RTX 3060 12 Go      | RTX 4090 24 Go           |
| VRAM      | 4 Go (modèle small) | 10 Go+ (large-v3-turbo)  |
| RAM       | 8 Go                | 16 Go+                   |
| Disque    | 5 Go                | 20 Go (cache de modèles) |
| Python    | 3.9+                | 3.11                     |
| CUDA      | 11.8+               | 12.1+                    |

**Jeton HuggingFace requis** pour la diarisation — acceptez la licence sur [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1).

**Recommandation Clore.ai :** RTX 3090 (~~$0.30–1.00/jour) pour le modèle large-v3-turbo avec taille de lot 16. RTX 4090 (~~$0.50–2.00/jour) pour un débit maximal avec une taille de lot de 32.

## Installation

```bash
# Installer WhisperX
pip install whisperx

# Vérifier le GPU
python -c "import torch; print(torch.cuda.get_device_name(0))"
```

Si vous rencontrez des conflits de version CUDA :

```bash
pip install torch==2.5.1+cu124 torchaudio==2.5.1+cu124 --index-url https://download.pytorch.org/whl/cu124
pip install whisperx
```

## Démarrage rapide

```python
import whisperx
import json

device = "cuda"
compute_type = "float16"  # "int8" pour moins de VRAM
batch_size = 16            # réduisez à 4-8 si la VRAM est limitée

# 1. Charger le modèle
model = whisperx.load_model("large-v3-turbo", device, compute_type=compute_type)

# 2. Charger et transcrire l'audio
audio = whisperx.load_audio("interview.mp3")
result = model.transcribe(audio, batch_size=batch_size)
print(f"Language: {result['language']}")

# 3. Aligner pour des horodatages au niveau des mots
model_a, metadata = whisperx.load_align_model(
    language_code=result["language"], device=device
)
result = whisperx.align(
    result["segments"], model_a, metadata, audio, device,
    return_char_alignments=False,
)

# 4. Afficher les résultats
for seg in result["segments"]:
    print(f"[{seg['start']:.2f}s → {seg['end']:.2f}s] {seg['text']}")
    for w in seg.get("words", []):
        print(f"  '{w['word']}' @ {w.get('start', 0):.2f}s")

# 5. Enregistrer
with open("transcript.json", "w") as f:
    json.dump(result, f, indent=2, ensure_ascii=False)
```

## Exemples d'utilisation

### Transcription avec diarisation des locuteurs

```python
import whisperx
import gc
import torch

device = "cuda"
HF_TOKEN = "hf_your_token_here"  # depuis huggingface.co/settings/tokens

# Étape 1 : Transcrire
model = whisperx.load_model("large-v3-turbo", device, compute_type="float16")
audio = whisperx.load_audio("meeting.mp3")
result = model.transcribe(audio, batch_size=16)

# Libérer la mémoire GPU avant de charger le modèle d'alignement
del model; gc.collect(); torch.cuda.empty_cache()

# Étape 2 : Aligner
model_a, metadata = whisperx.load_align_model(
    language_code=result["language"], device=device
)
result = whisperx.align(result["segments"], model_a, metadata, audio, device)
del model_a; gc.collect(); torch.cuda.empty_cache()

# Étape 3 : Diariser
diarize_model = whisperx.DiarizationPipeline(
    use_auth_token=HF_TOKEN, device=device
)
diarize_segments = diarize_model(audio, min_speakers=2, max_speakers=6)

# Étape 4 : Attribuer des locuteurs aux mots
result = whisperx.assign_word_speakers(diarize_segments, result)

for seg in result["segments"]:
    speaker = seg.get("speaker", "UNKNOWN")
    print(f"[{speaker}] [{seg['start']:.1f}s → {seg['end']:.1f}s] {seg['text']}")
```

### Utilisation en ligne de commande

```bash
# Transcription de base
whisperx audio.mp3 --model large-v3-turbo --device cuda

# Forcer la langue (plus rapide, évite la détection)
whisperx audio.mp3 --model large-v3-turbo --language en --device cuda

# Avec diarisation des locuteurs
whisperx audio.mp3 --model large-v3-turbo --diarize --hf_token hf_your_token

# Sortie de sous-titres SRT
whisperx audio.mp3 --model large-v3-turbo --output_format srt --output_dir ./subs/

# Mode faible VRAM
whisperx audio.mp3 --model medium --compute_type int8 --batch_size 4 --device cuda

# Traitement par lots d'un répertoire
for f in /data/audio/*.mp3; do
  whisperx "$f" --model large-v3-turbo --output_dir /data/transcripts/
done
```

### Script de génération SRT

```python
import whisperx

def transcribe_to_srt(audio_path, output_path, model_name="large-v3-turbo"):
    device = "cuda"
    model = whisperx.load_model(model_name, device, compute_type="float16")
    audio = whisperx.load_audio(audio_path)
    result = model.transcribe(audio, batch_size=16)

    model_a, metadata = whisperx.load_align_model(
        language_code=result["language"], device=device
    )
    result = whisperx.align(result["segments"], model_a, metadata, audio, device)

    with open(output_path, "w") as f:
        for i, seg in enumerate(result["segments"], 1):
            start = format_ts(seg["start"])
            end = format_ts(seg["end"])
            f.write(f"{i}\n{start} --> {end}\n{seg['text'].strip()}\n\n")

    print(f"SRT enregistré dans {output_path}")

def format_ts(seconds):
    h = int(seconds // 3600)
    m = int((seconds % 3600) // 60)
    s = int(seconds % 60)
    ms = int((seconds % 1) * 1000)
    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"

transcribe_to_srt("podcast.mp3", "podcast.srt")
```

## Benchmarks de performance

| Méthode         | Modèle             | Audio 1h    | GPU          | Vitesse approximative |
| --------------- | ------------------ | ----------- | ------------ | --------------------- |
| Whisper vanilla | large-v3           | \~60 min    | RTX 3090     | 1×                    |
| faster-whisper  | large-v3           | \~5 min     | RTX 3090     | \~12×                 |
| **WhisperX**    | **large-v3-turbo** | **\~1 min** | **RTX 3090** | **\~60×**             |
| **WhisperX**    | **large-v3-turbo** | **\~50 s**  | **RTX 4090** | **\~70×**             |

| Taille de lot | Vitesse (RTX 4090)  | VRAM  |
| ------------- | ------------------- | ----- |
| 4             | \~30× en temps réel | 6 Go  |
| 8             | \~45× en temps réel | 8 Go  |
| 16            | \~60× en temps réel | 10 Go |
| 32            | \~70× en temps réel | 14 Go |

## Conseils pour les utilisateurs de Clore.ai

* **Libérer la VRAM entre les étapes** — supprimer les modèles et appeler `torch.cuda.empty_cache()` entre transcription, alignement et diarisation
* **Jeton HuggingFace** — vous devez accepter la licence du modèle pyannote avant que la diarisation ne fonctionne ; définissez `HF_TOKEN` comme variable d'environnement
* **Ajustement de la taille de lot** — commencez par `batch_size=16`, réduisez à 4–8 sur des cartes 12 Go, augmentez à 32 sur des cartes 24 Go
* **`int8` calcul** — utiliser `compute_type="int8"` pour diviser par deux l'utilisation de la VRAM avec une perte de qualité minimale
* **Image Docker** — `pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime`
* **Cache de modèles persistant** — montez `/root/.cache/huggingface` pour éviter de retélécharger les modèles à chaque redémarrage du conteneur

## Dépannage

| Problème                         | Solution                                                                                                                            |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `CUDA out of memory`             | Réduire `batch_size`, utilisez `compute_type="int8"`, ou utilisez un modèle plus petit (medium, small)                              |
| La diarisation renvoie `UNKNOWN` | Assurez-vous que le jeton HuggingFace est valide et que vous avez accepté la licence pyannote                                       |
| `Aucun module nommé 'whisperx'`  | `pip install whisperx` — assurez-vous qu'il n'y a pas de faute de frappe (c'est `whisperx`, pas `whisper-x`)                        |
| Mauvais horodatages de mots      | Vérifiez que `whisperx.align()` est appelé après `transcribe()` — la sortie brute de Whisper manque de précision au niveau des mots |
| Détection de langue incorrecte   | Forcez la langue avec `--language en` ou `language="en"` dans l'API Python                                                          |
| Traitement lent                  | Augmentez `batch_size`, utilisez `large-v3-turbo` au lieu de `large-v3`, assurez-vous que le GPU n'est pas partagé                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-fr/audio-et-voix/whisperx.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.