# Video to MP3 Transcriptor - Instructions pour Claude

## À propos du projet
Ce projet est une API Node.js/Express pour télécharger des vidéos YouTube en MP3, les transcrire, les traduire et les résumer.

## Documentation

### Documentation API
La documentation complète de l'API se trouve dans **`docs/API.md`**.

**IMPORTANT** : Cette documentation doit TOUJOURS être maintenue à jour. Chaque fois qu'un endpoint est modifié, ajouté ou supprimé, la documentation doit être mise à jour en conséquence.

### Responsabilités de maintenance de la documentation

Quand tu modifies le code, tu DOIS mettre à jour `docs/API.md` si :
- Un nouvel endpoint est ajouté
- Un endpoint existant est modifié (paramètres, réponses, etc.)
- Un endpoint est supprimé
- Les modèles par défaut changent
- De nouveaux paramètres sont ajoutés
- Le format des réponses change

## Structure du projet

```
videotoMP3Transcriptor/
├── docs/
│   └── API.md              # Documentation complète de l'API
├── src/
│   ├── server.js           # Serveur Express et routes API
│   ├── services/
│   │   ├── youtube.js      # Téléchargement YouTube
│   │   ├── transcription.js # Transcription OpenAI
│   │   ├── translation.js  # Traduction GPT
│   │   └── summarize.js    # Résumé GPT-5.1
│   └── cli.js              # Interface en ligne de commande
├── public/                 # Interface web (si présente)
├── output/                 # Répertoire de sortie par défaut
├── .env                    # Variables d'environnement
└── package.json

```

## Configuration

### Port du serveur
- Port par défaut : **8888**
- Configurable via `process.env.PORT` dans `.env`

### Modèles par défaut
- **Transcription** : `gpt-4o-mini-transcribe`
- **Résumé** : `gpt-5.1`
- **Traduction** : `gpt-4o-mini` (hardcodé)

### Variables d'environnement requises
```env
OPENAI_API_KEY=sk-...
PORT=8888                  # optionnel
OUTPUT_DIR=./output        # optionnel
```

## Commandes importantes

```bash
# Lancer le serveur
npm run server

# Lancer le CLI
npm run cli

# Installer les dépendances
npm install
```

## Points d'attention

### Paramètres outputPath
Tous les endpoints supportent maintenant un paramètre `outputPath` optionnel pour spécifier un répertoire de sortie personnalisé. Si non spécifié, le répertoire par défaut `OUTPUT_DIR` est utilisé.

### Modèles de transcription disponibles
- `gpt-4o-mini-transcribe` (par défaut) - Rapide et économique
- `gpt-4o-transcribe` - Qualité supérieure
- `whisper-1` - Modèle original Whisper (supporte plus de formats)

### Formats de sortie
- **Transcription** : txt, json, srt, vtt (selon le modèle)
- **Traduction** : txt
- **Résumé** : txt

## Règles de développement

1. **Documentation d'abord** : Avant de modifier un endpoint, vérifie `docs/API.md`
2. **Après modification** : Mets à jour immédiatement `docs/API.md`
3. **Tests** : Redémarre le serveur après chaque modification
4. **Cohérence** : Garde la même structure de réponse pour tous les endpoints similaires

## Architecture des endpoints

### Endpoints streaming (SSE)
- `/download-stream`
- `/process-stream`
- `/summarize-stream`

Ces endpoints utilisent Server-Sent Events pour envoyer des mises à jour de progression en temps réel.

### Endpoints non-streaming
- `/download`
- `/process`
- Tous les endpoints POST avec upload de fichiers

Ces endpoints retournent une réponse unique une fois le traitement terminé.

## Maintenance

Lors de l'ajout de nouvelles fonctionnalités :
1. Implémente la fonctionnalité dans le service approprié (`src/services/`)
2. Ajoute les routes dans `src/server.js`
3. **Mets à jour `docs/API.md` IMMÉDIATEMENT**
4. Teste l'endpoint avec curl ou Postman
5. Vérifie que la documentation est claire et complète

## Notes importantes

- Le serveur doit toujours être sur le port **8888**
- Les clés API OpenAI sont requises pour transcription/traduction/résumé
- Le répertoire `output/` est créé automatiquement si inexistant
- Les fichiers uploadés sont stockés dans `OUTPUT_DIR`
- Les vidéos YouTube sont téléchargées en MP3 automatiquement