retrotoon-studio/README.md

🎬 RetroToon Studio

---

Pipeline IA de recomposition de dessins animés vintage en style moderne

Importez une vidéo rétro, extrayez les frames, segmentez les plans, et laissez l'IA regénérer chaque calque dans le style de votre choix.

---

🌟 Vue d'ensemble

RetroToon Studio est un NLE (Non-Linear Editor) spécialisé dans la recomposition artistique de dessins animés classiques. Il combine l'extraction vidéo frame-par-frame, la détection automatique de plans, la segmentation par calques (arrière-plan, personnages, objets) et la regénération IA pour transformer des animations vintage en œuvres modernes tout en préservant leur âme originale.

┌─────────────────────────────────────────────────────────────────────┐
│                        RETROTOON STUDIO                              │
├──────────┬──────────────┬───────────────┬──────────────┬────────────┤
│  IMPORT  │  DÉTECTION   │ SEGMENTATION  │ REGÉNÉRATION │   EXPORT   │
│  Vidéo   │  de Plans    │  par Calques  │  IA / Style  │   Vidéo    │
│  → Frames│  → Séquences │  → Masques    │  → Composite │   Final    │
└──────────┴──────────────┴───────────────┴──────────────┴────────────┘

---

✨ Fonctionnalités principales

🎞️ Import & Extraction Vidéo

Fonctionnalité	Description
Upload vidéo	MP4, WebM, MOV, AVI — stockage S3 intégré
Extraction client-side	Via HTMLVideoElement + Canvas (pas de FFmpeg requis)
3 modes d'import	Rapide (8fps/480p), Qualité (24fps/Original), Personnalisé
Résolution configurable	Original, 720p, 480p, 360p
Format de sortie	JPEG (léger) ou PNG (sans perte)
Barre de progression	Temps réel avec compteur de frames

🔍 Détection de Plans (Scene Detection)

Fonctionnalité	Description
Algorithme Chi-Squared	Comparaison d'histogrammes inter-frames
Hard cuts & Dissolves	Seuils adaptatifs pour les deux types de transition
Longueur minimale	Contrainte configurable pour éviter les faux positifs
Analyse LLM Vision	Description automatique de chaque plan via IA multimodale

🎨 Workspace NLE

Fonctionnalité	Description
Timeline complète	Séquences, marqueurs, piste audio, drag In/Out
6 modes de viewport	Original, Composite, Side-by-Side, Split, Overlay, Onion Skin
Loupe duale	Zoom 2-8×, forme cercle/carré, grille pixel, verrouillage
Transport	Play, Pause, Frame-by-frame, Skip, raccourcis clavier
Audio synchronisé	Lecture HTMLAudioElement avec resync drift 100ms
Raccourcis personnalisables	Hook dédié + persistance localStorage

🧠 Intelligence Artificielle

Module	Description
Assistant Opérateur	Chat en langage naturel, actions rapides, pipeline autonome
Segmentation	Architecture SAM 2 (auto/point/box), propagation temporelle
Regénération	Arrière-plans par prompt, personnages avec style transfer
Multi-fournisseur LLM	Built-in Manus, Gemini 2.5 Flash (configurable)
Character Sheets	Cohérence visuelle via LoRA/IP-Adapter (architecture prête)

🏗️ Architecture Extensible

Composant	Description
Admin Panel	CRUD moteurs IA, config LLM, test connectivité, mode simulation
Services externes	FFmpeg, SAM 2, ControlNet — endpoints configurables
Plugin-ready	Mode simulé par défaut, bascule automatique vers services réels
Export	Pipeline compositing + assemblage vidéo (prêt pour FFmpeg)

---

🛠️ Stack Technique

┌─────────────────────────────────────────────────────┐
│                    FRONTEND                           │
│  React 19 · Tailwind 4 · shadcn/ui · Wouter         │
│  tRPC Client · Sonner · Lucide Icons                 │
├─────────────────────────────────────────────────────┤
│                    BACKEND                            │
│  Express 4 · tRPC 11 · Superjson · Drizzle ORM      │
│  Manus OAuth · S3 Storage · LLM Integration         │
├─────────────────────────────────────────────────────┤
│                   DATABASE                            │
│  MySQL/TiDB · Drizzle Migrations · 8 tables          │
├─────────────────────────────────────────────────────┤
│                  IA / SERVICES                        │
│  Gemini 2.5 Flash · Manus Built-in LLM              │
│  Image Generation · Voice Transcription              │
└─────────────────────────────────────────────────────┘

---

📁 Structure du Projet

retrotoon-studio/
├── client/                     # Frontend React
│   ├── src/
│   │   ├── pages/              # Pages principales
│   │   │   ├── Home.tsx        # Dashboard projets
│   │   │   ├── NewProject.tsx  # Import vidéo + extraction
│   │   │   ├── ProjectWorkspace.tsx  # NLE complet
│   │   │   └── AdminPanel.tsx  # Administration IA
│   │   ├── components/         # Composants réutilisables
│   │   │   ├── ViewportPanel.tsx     # Viewport 6 modes
│   │   │   ├── TimelinePanel.tsx     # Timeline NLE
│   │   │   ├── LayersPanel.tsx       # Gestion calques
│   │   │   ├── CharactersPanel.tsx   # Character sheets
│   │   │   └── AssistantPanel.tsx    # Chat IA
│   │   ├── contexts/           # Contextes React
│   │   └── hooks/              # Hooks personnalisés
│   └── index.html
├── server/                     # Backend Express + tRPC
│   ├── routers.ts              # Procédures tRPC (auth + features)
│   ├── db.ts                   # Helpers base de données
│   ├── uploadRoute.ts          # Upload vidéo/assets/frames
│   ├── llmConfig.ts            # Configuration multi-LLM
│   ├── assistantOperator.ts    # Pipeline assistant IA
│   ├── sceneDetection.ts       # Détection de plans
│   ├── segmentation.ts         # Segmentation calques
│   └── _core/                  # Infrastructure (OAuth, LLM, Storage)
├── drizzle/                    # Schéma DB + migrations
│   └── schema.ts              # 8 tables (projects, frames, sequences...)
├── shared/                     # Types & constantes partagés
└── server/*.test.ts            # Tests Vitest (49 tests)

---

🗄️ Modèle de Données

erDiagram
    USERS ||--o{ PROJECTS : owns
    PROJECTS ||--o{ SEQUENCES : contains
    PROJECTS ||--o{ FRAMES : contains
    PROJECTS ||--o{ CHARACTERS : defines
    SEQUENCES ||--o{ LAYERS : has
    FRAMES {
        int id PK
        int projectId FK
        int frameIndex
        text originalUrl
        text maskUrl
        text backgroundUrl
        text foregroundUrl
        text regeneratedBgUrl
        text compositedUrl
    }
    PROJECTS {
        int id PK
        varchar name
        enum status
        int fps
        int totalFrames
        int width
        int height
    }

---

🚀 Démarrage Rapide

# Cloner le dépôt
git clone https://git.cosmolan.fr/tarzzan/retrotoon-studio.git
cd retrotoon-studio

# Installer les dépendances
pnpm install

# Configurer les variables d'environnement
cp .env.example .env
# Éditer .env avec vos clés API

# Lancer en développement
pnpm dev

Variables d'environnement requises

Variable	Description
DATABASE_URL	Connexion MySQL/TiDB
JWT_SECRET	Secret de signature des sessions
GEMINI_API_KEY	Clé API Google Gemini (LLM)
VITE_APP_ID	ID application OAuth
OAUTH_SERVER_URL	URL backend OAuth

---

🧪 Tests

# Exécuter tous les tests
pnpm test

# 49 tests couvrant :
# ✓ Routeurs tRPC (24 tests)
# ✓ Détection de scènes (9 tests)
# ✓ Configuration services (7 tests)
# ✓ Raccourcis clavier (6 tests)
# ✓ Validation API Gemini (2 tests)
# ✓ Auth logout (1 test)

---

🎯 Roadmap

✅ Phase 1 — Fondations (Complète)

• Architecture full-stack TypeScript end-to-end
• Import vidéo + extraction frames client-side (3 modes)
• Workspace NLE avec timeline et viewport multi-modes (6 vues)
• Détection de plans par histogramme chi-squared
• Gestion des calques et personnages avec character sheets
• Assistant IA en langage naturel avec pipeline autonome
• Administration des moteurs IA (CRUD, test, simulation)
• Loupe duale avec grille pixel et verrouillage
• Raccourcis clavier personnalisables
• 49 tests unitaires Vitest passants
• Zéro erreur TypeScript

🔄 Phase 2 — Intégrations IA (En cours)

• Support multi-LLM (Gemini 2.5 Flash configuré)
• Connexion FFmpeg externe pour extraction HD
• Intégration SAM 2 pour segmentation réelle
• ControlNet pour contraintes de pose
• LoRA training pour cohérence personnages
• Outil d'annotation/masque sur le viewport

📋 Phase 3 — Production (Planifiée)

• Export vidéo final avec audio synchronisé
• Batch processing multi-projets
• Collaboration temps réel (WebSocket)
• API publique pour intégrations tierces
• Miniatures de frames dans la timeline

---

🎨 Design

Le thème visuel Blueprint Architectural utilise un fond bleu royal avec une grille technique, une typographie sans-serif blanche et des accents lumineux. Ce choix esthétique évoque la précision d'un plan d'architecte appliquée à la recomposition artistique.

Élément	Valeur
Fond principal	Bleu royal foncé (oklch(0.25 0.05 250))
Grille	Lignes techniques semi-transparentes
Typographie	Inter / JetBrains Mono
Accents	Bleu électrique, vert néon, violet
Mode	Dark theme exclusif

---

📐 Architecture Technique

Flux de données

Utilisateur → Upload vidéo → S3 Storage
                ↓
         Extraction frames (Canvas API)
                ↓
         Enregistrement DB (frames-batch)
                ↓
    ┌───────────┼───────────────┐
    ↓           ↓               ↓
Détection   Segmentation   Regénération
de plans    par calques    IA / Style
    ↓           ↓               ↓
    └───────────┼───────────────┘
                ↓
         Compositing final
                ↓
         Export vidéo

Procédures tRPC principales

Namespace	Procédures	Description
projects	list, get, create, delete	CRUD projets
frames	getByIndex, list	Accès frames
sequences	list, create, update	Gestion séquences
layers	list, create, toggleVisibility, toggleLock	Calques
characters	list, create, update, delete	Personnages
assistant	chat, analyzeFrame	IA conversationnelle
admin	config.*, engines.*, services.*	Administration

---

👤 Auteur

William MERI — Architecte logiciel & Transformation numérique

🌐 Web	systemd.cosmolan.fr
📧 Email	william.meri@gmail.com
🐙 Git	git.cosmolan.fr/tarzzan
🏢 Association	System D 3.0 — Accompagnement à la transformation numérique

---

📄 Licence

Ce projet est un logiciel propriétaire développé dans le cadre de l'association System D 3.0. Tous droits réservés © 2026 William MERI.

---

Fait avec ❤️ et beaucoup d'IA

RetroToon Studio — Donnez une nouvelle vie à vos dessins animés préférés