SupoClip : transformer automatiquement une longue vidéo en courtes vidéos verticales
SupoClip résout un problème très concret : à partir d'une longue vidéo — podcast, interview, rediffusion en direct — il identifie automatiquement les 3 à 7 extraits les plus susceptibles de devenir viraux, les classe selon leur impact potentiel, puis les rend en vidéos verticales 9:16 avec sous-titres mot à mot, recadrage centré sur le visage et accroche de titre. Tout le processus s'exécute sur votre propre matériel, sans filigrane ni verrouillage par plateforme.
La chaîne technique se compose de cinq étapes : AssemblyAI ou Whisper pour la transcription avec horodatage mot à mot ; un LLM sélectionne les moments forts à partir de la transcription et les note ; la détection de visages détermine qui centrer dans le cadre vertical ; les sous-titres s'affichent mot par mot selon la chronologie ; enfin FFmpeg assemble et exporte. Le front-end est construit avec Next.js, le back-end avec FastAPI, les tâches en arrière-plan sont gérées par un worker ARQ qui traite une file d'attente Redis, et PostgreSQL stocke les données utilisateurs et tâches.
Dépendances principales et environnement
Vérifiez d'abord les prérequis :
- Git
- Docker Engine ou Docker Desktop, avec le plugin Compose
- Au moins 10 Go d'espace disque disponible (les fichiers vidéo, le cache des modèles et les fichiers temporaires de rendu occupent de la place)
- Un processeur suffit, mais la transcription et le rendu seront lents ; si vous avez un GPU NVIDIA, vous pouvez désactiver
BACKEND_CPU_ONLYpour accélérer
Deux clés sont requises :
- Clé API AssemblyAI : pour la transcription, chemin par défaut
- Une clé d'un fournisseur LLM : Google, OpenAI, Anthropic ou OpenRouter, au choix
Pour une exécution entièrement locale, vous pouvez remplacer la transcription par Whisper et le modèle de sélection des extraits par Ollama, sans aucune clé API.
Arborescence du projet
supoclip/
├── frontend/ # Front-end Next.js, port 3107, proxy d'authentification vers le back-end
├── backend/ # Back-end FastAPI, port 8000, documentation API interactive /docs
├── worker/ # Processus de tâches ARQ en arrière-plan : transcription, analyse, rendu
├── mcp/ # Serveur MCP, appelable depuis Claude/Cursor
├── docs/ # Documentation : installation, configuration, dépannage, etc.
├── scripts/ # Scripts d'exploitation, réparation de base de données, etc.
├── docker-compose.yml # Orchestration de cinq services : frontend/backend/worker/postgres/redis
└── .env.example # Modèle des variables d'environnement
Les données sont stockées dans des volumes nommés : postgres_data, redis_data, uploads, clips. Le back-end monte également deux répertoires locaux, backend/fonts et backend/transitions, pour les polices de sous-titres et les ressources de transitions.
Guide pas à pas de déploiement
1. Cloner le dépôt et préparer le fichier d'environnement
git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env
Modifiez .env et remplissez au moins ces trois champs :
ASSEMBLY_AI_API_KEY=votre_clé_assemblyai
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=votre_clé_google
2. Configurer le modèle de sélection des extraits
La variable LLM détermine le modèle qui choisit les extraits. En plus des modèles cloud comme Gemini, GPT, Claude, vous pouvez utiliser le préfixe ollama: pour pointer vers n'importe quel service compatible avec le protocole v1/chat/completions. Par exemple, avec Defapi pour accéder à un modèle local :
LLM=ollama:identifiant_de_votre_modèle
OLLAMA_BASE_URL=https://api.defapi.org/v1
OLLAMA_API_KEY=votre_clé_defapi
Le préfixe ollama: de SupoClip ne fait que sélectionner le type de client ; il ne force pas l'exécution locale d'Ollama. Dans le code, OllamaProvider utilise AsyncOpenAI avec une base_url et une clé API, donc tout service compatible avec le protocole de complétion de chat d'OpenAI fonctionne. Defapi est l'un de ces services, à environ la moitié du prix des canaux officiels, et la plupart des modèles sont compatibles avec les trois protocoles v1/chat/completions, v1/messages et v1beta/models/. Le processus de sélection ne peut être validé que par des tests réels ; la transcription et l'édition dans le studio restent des chemins indépendants.
3. Construire et démarrer
./start.sh
Si vous n'avez pas la patience avec le script, vous pouvez aussi le faire manuellement :
docker-compose up -d --build
La première construction récupère les images et installe les dépendances ; sur un CPU, cela peut prendre plusieurs minutes. Surveillez la progression avec :
docker-compose logs -f
Lorsque les cinq services passent à healthy, c'est prêt :
docker-compose ps
4. Vérifier l'état de santé des services
Ouvrez ces adresses pour vérifier :
- Front-end : http://localhost:3107
- Vérification de santé du back-end : http://localhost:8000/health
- Documentation API interactive : http://localhost:8000/docs
La sortie de docker-compose ps devrait afficher les cinq conteneurs supoclip-frontend, supoclip-backend, supoclip-worker, supoclip-postgres, supoclip-redis.
5. Créer un compte et téléverser une vidéo
Ouvrez la page d'accueil du front-end dans un navigateur et créez un compte. La page d'accueil propose deux méthodes d'entrée : coller un lien YouTube/Twitch/Kick, ou téléverser directement un fichier vidéo local. Notez que la limite de téléversement est de 4 Go par défaut, ce qui est suffisant pour une vidéo 1080p complète avec un débit binaire normal.
6. Prévisualiser, éditer et exporter des courtes vidéos verticales
Après avoir soumis une tâche, la page de la tâche affiche la progression en temps réel : l'état de chaque étape (transcription, analyse IA, rendu) est transmis. Une fois terminé, vous pouvez voir pour chaque extrait la durée, un extrait de la transcription, la raison du choix par l'IA et le score de potentiel viral.
En entrant dans le studio d'édition, vous pouvez effectuer les ajustements suivants :
- Faire glisser les bords d'un extrait pour couper le début et la fin
- Diviser un extrait long en plusieurs segments
- Fusionner plusieurs extraits
- Réécrire le texte des sous-titres
- Changer le style des sous-titres (police, animation, taille, couleur)
- Exporter selon les préréglages de plateforme : TikTok, Reels, Shorts
Lors de l'exportation, choisissez « Vertical output » pour obtenir une vidéo verticale 9:16, avec le recadrage centré sur le visage et les sous-titres mot à mot déjà gravés.
Dépannage courant
La page front-end ne répond pas
Vérifiez le port utilisé par l'hôte. Le modèle par défaut définit FRONTEND_PORT=3107 ; si vous avez effectué une mise à niveau depuis une version antérieure, l'absence de cette variable dans .env entraîne un repli sur 3001. Utilisez docker-compose port frontend 3107 pour voir l'identifiant réel.
Erreur de connexion : Invalid origin
NEXT_PUBLIC_APP_URL et BETTER_AUTH_URL doivent correspondre exactement à l'adresse du navigateur, y compris le protocole et le port. localhost et 127.0.0.1 sont deux origines différentes. Si vous accédez via un autre domaine ou port, définissez BETTER_AUTH_TRUSTED_ORIGINS avec une liste explicite séparée par des virgules ; les caractères génériques ne sont pas pris en charge.
La tâche reste bloquée à queued
Commencez par consulter les logs du worker. docker-compose logs -f worker révélera les éventuels problèmes. Ensuite, vérifiez le battement cardiaque du worker avec curl -f http://localhost:8000/health/worker ; une réponse 503 indique que le worker est déconnecté ou que Redis est injoignable. Le battement cardiaque ARQ expire environ toutes les 31 secondes.
La transcription est bloquée à 30%
Cette étape appelle AssemblyAI. Vérifiez dans les logs du back-end que la clé API est valide et que le quota du compte est suffisant. L'interrogation a un délai d'attente global, par défaut 900 secondes ; en cas de dépassement, la même tâche de transcription est relancée sans double facturation. Pour les vidéos longues, vous pouvez augmenter ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS.
Erreur du modèle de sélection ou format de sortie incorrect
Le préfixe LLM et la clé du fournisseur doivent correspondre : ollama: doit être associé à OLLAMA_BASE_URL et OLLAMA_API_KEY, google-gla: à GOOGLE_API_KEY, et ainsi de suite. Si le modèle local renvoie un JSON non conforme, l'agent réessaiera jusqu'à deux fois (output_retries=2). Choisir un modèle avec une meilleure capacité à suivre les instructions résout généralement le problème.
L'inscription affiche Failed to create account
Cela vient probablement d'un schéma de base de données en retard par rapport au code. Exécutez le script de réparation idempotente, qui ajoute uniquement des colonnes sans toucher aux données existantes :
docker compose exec -T postgres psql -U supoclip -d supoclip < scripts/selfhost-schema-repair.sql
N'exécutez surtout pas prisma db push ou prisma migrate deploy sur cette base ; le back-end gère lui-même un ensemble de tables que Prisma ne connaît pas, et db push les supprimerait.
Lecture supplémentaire / directions avancées
- Itinéraire entièrement local : remplacez
TRANSCRIPTION_PROVIDERparwhisperet utilisezLLM=ollama:...avec un service Ollama local. L'adresse Ollama par défaut dans Docker esthttp://host.docker.internal:11434/v1, donc l'Ollama de la machine hôte doit écouter sur le port correspondant. - Intégration MCP : le répertoire
mcp/du dépôt fournit un serveur MCP qui permet d'appeler les capacités d'édition de SupoClip depuis des clients tels que Claude ou Cursor. - API REST : générez une clé API dans
/settings/api-keyset appelez directement les interfaces du back-end, ce qui convient au traitement par lots scripté. - B-roll : définissez
PEXELS_API_KEY; après la sélection IA, des vidéos gratuites de Pexels seront automatiquement associées comme images d'illustration. - Limites de licence : la version actuelle est soumise à la SupoClip Noncommercial Source License 1.1 ; l'utilisation non commerciale et la monétisation par les créateurs individuels sont gratuites, mais les entreprises, les institutions, les équipes ou les services de montage pour autrui doivent envoyer un courriel pour demander une autorisation écrite. Avant de commencer, lisez le fichier
LICENSE, en particulier la définition des « créateurs individuels ».