videotomp3transcriptor/CLAUDE.md

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

OPENAI_API_KEY=sk-...
PORT=8888                  # optionnel
OUTPUT_DIR=./output        # optionnel

Commandes importantes

# 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