# VideoToMP3Transcriptor - YouTube Download & Transcription Service

**Status**: DONE
**Type**: Utility Service (Node.js)
**Location**: `C:\Users\alexi\Documents\projects\videotoMP3Transcriptor`
**Created**: 24 novembre 2025
**Shipped**: 25 novembre 2025
**Moved to DONE**: 30 novembre 2025

---

## Vue d'ensemble

**Service complet pour télécharger vidéos YouTube en MP3, transcrire, traduire et résumer.**

### Use Cases
- Télécharger cours vidéo en MP3
- Transcrire automatiquement (chinois, français, anglais, etc.)
- Traduire transcriptions
- Générer résumés AI

---

## Stack Technique

**Backend**:
- Node.js 18+
- Express (REST API + SSE streaming)
- OpenAI API (Whisper + GPT-4o-mini + GPT-5.1)

**CLI Tools**:
- yt-dlp (YouTube download)
- ffmpeg (audio conversion)

**Port**: 8888 (par défaut)

---

## Features

### Download
- ✅ Single YouTube video → MP3
- ✅ Playlist complète → MP3 batch
- ✅ Custom output directory

### Transcription
- ✅ 3 modèles dispo :
  - `gpt-4o-mini-transcribe` (défaut) - Rapide, économique
  - `gpt-4o-transcribe` - Qualité supérieure
  - `whisper-1` - Legacy (supports SRT/VTT)
- ✅ Multi-langue (auto-detect ou spécifié)
- ✅ Formats : txt, json, srt, vtt

### Traduction
- ✅ GPT-4o-mini
- ✅ Multi-langue support

### Résumé
- ✅ GPT-5.1
- ✅ Résumé intelligent contextuel

### Interfaces
- ✅ CLI (commands via npm run)
- ✅ REST API (endpoints POST/GET)
- ✅ SSE Streaming (progress en temps réel)
- ✅ Interface Web (public/)

---

## API Endpoints

### Core Endpoints

**POST /download** - Télécharge vidéo/playlist en MP3
```bash
curl -X POST http://localhost:8888/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://youtube.com/watch?v=VIDEO_ID"}'
```

**POST /transcribe** - Transcrit fichier audio existant
```bash
curl -X POST http://localhost:8888/transcribe \
  -H "Content-Type: application/json" \
  -d '{"filePath": "./output/video.mp3", "language": "en"}'
```

**POST /process** - Download + Transcribe en un appel
```bash
curl -X POST http://localhost:8888/process \
  -H "Content-Type: application/json" \
  -d '{"url": "URL", "language": "zh", "format": "txt"}'
```

### SSE Streaming Endpoints

**POST /download-stream** - Download avec progress temps réel
**POST /process-stream** - Process avec updates streaming
**POST /summarize-stream** - Résumé avec streaming

### Utility Endpoints

**GET /health** - Health check
**GET /info?url=URL** - Info vidéo/playlist
**GET /files-list** - Liste fichiers téléchargés
**GET /files/:filename** - Download fichier spécifique

---

## Configuration

**Environment Variables** (`.env`):
```env
OPENAI_API_KEY=sk-...
PORT=8888
OUTPUT_DIR=./output
```

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

---

## Usage

### CLI

```bash
# Download vidéo
npm run cli download "https://youtube.com/watch?v=VIDEO_ID"

# Transcrire fichier
npm run cli transcribe ./output/video.mp3 -l fr

# Download + Transcribe
npm run cli process "URL" -l en

# Info vidéo
npm run cli info "URL"
```

### Linux Scripts (shortcuts)

```bash
# Make executable (first time)
chmod +x scripts/*.sh

# Download
./scripts/download.sh "URL"

# Transcribe
./scripts/transcribe.sh ./output/file.mp3 zh

# Process all-in-one
./scripts/process.sh "URL" fr

# Start server
./scripts/server.sh
```

### API Server

```bash
# Start server
npm run server

# Server runs on http://localhost:8888
```

---

## Structure Projet

```
videotoMP3Transcriptor/
├── docs/
│   └── API.md              # Documentation API complète
├── src/
│   ├── server.js           # Express server + routes
│   ├── cli.js              # CLI interface
│   └── services/
│       ├── youtube.js      # YouTube download
│       ├── transcription.js # OpenAI Whisper
│       ├── translation.js  # GPT translation
│       └── summarize.js    # GPT-5.1 summarization
├── scripts/                # Linux convenience scripts
│   ├── download.sh
│   ├── transcribe.sh
│   ├── process.sh
│   ├── server.sh
│   └── info.sh
├── public/                 # Web interface
├── output/                 # Downloaded files (default)
├── .env                    # Configuration
└── package.json
```

---

## Git Activity

**Commits**: 2 (24-25 nov 2025)

**Timeline**:
- 24 nov : Initial commit (download + transcription)
- 25 nov : Add AI summarization (GPT-5.1)

**Status**: Shipped et fonctionnel

---

## Use Cases Actuels

### 1. Cours Chinois
- Download cours vidéo YouTube
- Transcription automatique chinois
- Révision texte pour Anki

### 2. Contenu Éducatif
- Vidéos diverses langues
- Génération transcriptions
- Traduction si besoin

### 3. Prototype pour Homework Bot
- **Code réutilisable** :
  - `services/transcription.js` → Whisper integration
  - `services/youtube.js` → Video download
  - Pattern SSE streaming → Feedback temps réel
- **Overlap** : 50% du code homework bot déjà écrit ici

---

## Relation avec Autres Projets

### Chinese Audio TTS Pipeline (PAUSE)
**Verdict** : OBSOLÈTE
- videotoMP3 fait déjà exactement ça
- Pas besoin de projet séparé
- **Action** : ARCHIVE chinese_audio_tts_pipeline

### WeChat Homework Bot (WIP)
**Synergies** :
- Whisper API transcription ✅
- GPT-4 API correction (similaire résumé) ✅
- File upload/processing ✅
- Node.js/Express backend ✅

**Réutilisation** : Copy/paste `services/transcription.js` dans homework bot

---

## Pourquoi DONE

**Critères "DONE"**:
- ✅ Shipped et fonctionnel
- ✅ Utilisé en production (cours chinois)
- ✅ Pas de développement actif prévu
- ✅ Maintenance seulement si bugs

**Pas un projet "abandonné"** : C'est un **service terminé et opérationnel**.

**Différence avec WIP** :
- WIP = Développement actif en cours
- DONE = Shipped, maintenance uniquement

---

## Installation & Démarrage Rapide

### Prerequisites

```bash
# Windows
winget install yt-dlp
winget install ffmpeg

# macOS
brew install yt-dlp ffmpeg

# Linux
sudo apt install yt-dlp ffmpeg
```

### Setup

```bash
cd C:\Users\alexi\Documents\projects\videotoMP3Transcriptor

# Install dependencies
npm install

# Configure
cp .env.example .env
# Edit .env: Add OPENAI_API_KEY

# Start server
npm run server

# Or use CLI
npm run cli download "https://youtube.com/watch?v=..."
```

---

## Documentation

**API complète** : `docs/API.md` dans le repo

**Maintenance** : Documentation toujours à jour avec le code

---

## Performance

**Transcription** :
- 2min audio → ~10-15s (gpt-4o-mini-transcribe)
- Dépend latence API OpenAI

**Download** :
- Dépend vitesse YouTube + taille fichier
- Progress visible via SSE streaming

---

## Coûts

**OpenAI API** (estimation 20 vidéos/mois, 10min moy) :
- Transcription : 20 × 10min × $0.006/min = **$1.20/mois**
- Résumé : 20 × $0.02 = **$0.40/mois**
- **Total** : ~**$1.60/mois**

**Infrastructure** : 0€ (local)

---

## Liens

**Repo Git**: `C:\Users\alexi\Documents\projects\videotoMP3Transcriptor`

**Documentation API**: `docs/API.md`

**CLAUDE.md**: Instructions développement et maintenance

---

## Notes

**Créé** : 24 novembre 2025
**Shipped** : 25 novembre 2025
**Moved to DONE** : 30 novembre 2025
**Auteur** : Alexis Trouvé

**Pattern de travail** : Fast shipping (2 jours conception → shipped)

**Lesson learned** : Service utilitaire bien scopé = 2 jours de dev = Utilisable immédiatement

---

**Tags** : `#nodejs` `#youtube` `#whisper` `#transcription` `#openai` `#gpt` `#done`