FunkePublishing/skill-promo-video

promo-video

Assemblez des vidéos promotionnelles courtes à partir de clips bruts. Portrait, carré ou paysage. Intro/outro optionnel rendu avec Blender, musique optionnelle générée par IA.

La compétence est agnostique de l'agent hôte : elle DOIT fonctionner de manière identique sur tous les environnements qui implémentent la norme Agent Skills (https://agentskills.io) — Claude, Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, Cline, OpenCode, OpenHands, Goose, Kiro, Junie, et autres. Ne jamais dépendre d'outils spécifiques à l'hôte (pas de AskUserQuestion, pas de commandes slash, pas de MCP sauf s'il est explicitement disponible). Menez toutes les interactions avec l'utilisateur sous forme de messages de discussion normaux.

Quand l'utiliser

• « Assemble ces clips en un reel de 30 secondes. »
• « Construis-moi une vidéo promo de hackathon en portrait. »
• « J'ai un dossier de vidéos de téléphone — fais un clip social 1080×1920 avec musique. »
• « Génère une promo avec intro logo + outro cœur + piste de fond. »
• L'utilisateur fait référence à un répertoire de fichiers .mov/.mp4 et souhaite un livrable unique.

Prérequis

• ffmpeg dans le PATH, compilé avec libx264, aac et prores_ks (ce dernier n'est nécessaire que pour les MOV d'intro/outro avec canal alpha).
• Python 3.9+.
• Installer une fois les dépendances Python : pip install -r requirements.txt depuis le dossier de la compétence.
• Optionnel : un fichier .env à la racine du projet contenant SUNO_API_KEY pour activer la génération musicale. La compétence détecte automatiquement si la clé est définie et ne propose la génération musicale que dans ce cas.
• Optionnel : Blender MCP disponible dans l'agent hôte pour produire les rendus d'intro/outro. Voir references/blender_mcp.md.

Flux par défaut (basé sur le dialogue)

Étape 0 — Détecter si les clips ont changé depuis la dernière exécution

Avant de poser des questions, vérifiez si l'utilisateur reprend une session précédente. Si gallery/.clips_snapshot.json existe (ou si l'utilisateur vous dirige vers un dossier de clips utilisé auparavant), exécutez :

python scripts/clip_diff.py <clips_dir>

• Code de sortie 0 — le dossier de clips correspond à la dernière capture. Continuez.
• Code de sortie 1 — écart. Le rapport liste les clips nouveaux / supprimés / modifiés. Affichez-le à l'utilisateur, puis proposez de réexécuter scripts/gallery.py pour que la galerie prenne en compte les nouveaux clips. Les sélections existantes pour les clips toujours présents restent intactes.
• Code de sortie 2 — pas encore de capture. Première exécution normale, continuez.

Ne SAUTEZ PAS cette étape lors de la reprise d'un projet existant — travailler silencieusement avec une galerie / selection.json obsolète est le bug classique « où sont passés mes nouveaux clips ? ».

Questions

Au début, posez à l'utilisateur les questions ci-dessous, dans l'ordre. Acceptez des réponses naturelles ; ne présentez pas d'interface à choix multiples sauf si l'hôte le supporte. Pour chaque question, acceptez aussi « décide à ma place » et appliquez la valeur par défaut raisonnable.

1. Format cible. 1080×1920 portrait (par défaut), 1920×1080 paysage, ou 1080×1080 carré. Tailles personnalisées autorisées.
2. Source des clips. Chemin absolu ou relatif vers un dossier contenant les clips bruts. .mov, .mp4, .m4v sont pris en charge.
3. Durée cible en secondes. (Typique : 20 à 45 s.)
4. Musique. Une des options : (a) fichier audio existant, (b) générer via Suno (ne proposer que si SUNO_API_KEY est défini), (c) pas de musique.
5. Intro. Une des options : aucune, image fixe (chemin), générée par Blender MCP.
6. Outro. Mêmes choix que pour l'intro.
7. Mode réalisateur. Oui ou non. Si oui, suivez references/director_mode.md au lieu de continuer linéairement ici.

Ensuite, gérez la sélection des clips. Proposez deux chemins :

A) Galerie visuelle (recommandée pour plus de 10 clips ou quand l'utilisateur souhaite voir les images avant de choisir les repères). Exécutez scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N — cela génère gallery/gallery.html avec des miniatures, des curseurs ENTRÉE/SORTIE, un curseur de vitesse et un aperçu de la plage. Dites à l'utilisateur de l'ouvrir dans un navigateur, de choisir les clips, de définir les repères, puis de cliquer sur « Exporter selection.json ». Le fichier téléchargé est prêt pour build.py.

B) Dialogue en ligne (adapté pour les petits lots ou quand aucun navigateur n'est disponible). Parcourez chaque clip vous-même :

• cue_in et cue_out en secondes (plage de rognage)
• speed multiplicateur (1.0 = original)
• fixed: true si le timing/la vitesse sont réglés manuellement, false pour des remplissages libres (par défaut : 0,6 s à partir du milieu, vitesse 1.0)

Proposez « Donne-moi les valeurs par défaut » — choisissez tous les clips par ordre alphabétique, valeurs libres par défaut, jusqu'à la durée cible.

Dans les deux cas, le résultat est un fichier selection.json conforme au templates/selection.schema.json. Validez avant de continuer.

Construction

Une fois selection.json valide, exécutez :

python <skill>/scripts/build.py <selection.json> --out output/<name>.mp4

build.py écrit les artefacts intermédiaires sous build/ (relatif au répertoire de travail courant) : build/normalized/, build/trimmed/, build/montage.mp4, build/composed.mp4. Supprimez build/ pour forcer un rendu complet.

Chaque sous-module sous scripts/ peut également être exécuté de manière autonome — utile pour itérer sur une étape sans reconstruire tout le pipeline. Chacun accepte un argument --help.

Mode réalisateur (optionnel)

Option activable. Voir references/director_mode.md pour les invites de rôle. La compétence déploie quatre rôles séquentiels — Narrateur → Monteur → Compositeur → Superviseur — qui partagent selection.json comme état. Chaque rôle lit le JSON actuel et écrit ses mises à jour en retour. À utiliser lorsque l'utilisateur demande « un processus plus guidé » ou « guide-moi comme un producteur ».

Génération musicale (optionnelle)

Si l'utilisateur a choisi « générer via Suno », déléguez l'étape musicale au sous-agent Song-Builder défini dans references/song_builder_agent.md. Ce sous-agent :

1. Demande à l'utilisateur le genre, l'ambiance, la plage BPM, la structure des sections, instrumental actif/inactif, et prend la durée de la vidéo comme durée.
2. Formule une invite Suno + des balises de style.
3. Appelle scripts/music.generate_song(spec) — fournissez takes > 1 si l'utilisateur souhaite des options à comparer.
4. Rogne et fond le « take » choisi à la durée de la vidéo.
5. Écrit le chemin final du mp3 dans selection.json sous audio.

Si l'hôte fournit un mécanisme de sous-agent (par exemple l'outil Agent de Claude Code), utilisez-le. Sinon, jouez le rôle en ligne dans le même fil de discussion.

Intégration Blender MCP (optionnelle)

Assistance uniquement — cette compétence ne fournit pas de scène Blender.

Si l'utilisateur souhaite une intro ou un outro rendu avec Blender, déléguez au sous-agent Blender-Builder défini dans references/blender_builder_agent.md. Il prend en charge tout le flux : vérification préalable (vérifier que Blender + MCP sont réellement joignables sur cet hôte), entretien de conception (direction visuelle, couleurs, durée), construction de la scène, aperçu itératif, rendu en ProRes 4444 alpha MOV, et transmission du chemin MOV dans selection.json.

Si l'hôte fournit un mécanisme de sous-agent (par exemple l'outil Agent de Claude Code), lancez-le. Sinon, jouez le rôle en ligne. Le flux de dialogue principal doit invoquer le Blender-Builder chaque fois que l'utilisateur a choisi « généré par Blender MCP » pour l'intro ou l'outro à l'étape 5 du questionnaire.

La documentation de configuration (installer Blender, installer le serveur MCP, l'enregistrer auprès de l'hôte) se trouve dans references/blender_mcp.md. Le sous-agent Blender-Builder s'appuie sur ce document lorsque l'utilisateur doit configurer la pile pour la première fois.

Récupération d'erreurs

• Si un clip échoue à la normalisation (cas particulier de codec / résolution), build.py se termine avec un code non nul et un message clair sur stderr pointant vers le fichier problématique. Demandez à l'utilisateur s'il souhaite ignorer le clip ou enquêter.
• Si Suno renvoie une erreur 4xx ou expire, proposez à l'utilisateur de réessayer, de passer à « fichier existant » ou de continuer sans musique.
• Ne supprimez jamais silencieusement des clips. Ne remplacez jamais un fichier de sortie existant sans confirmation, sauf si --force est passé.

Notes de style pour cette compétence

• Ne jamais supposer d'outils spécifiques à l'hôte. Tout dialogue est une simple discussion.
• Montrez votre travail. Lors du rognage, dites à l'utilisateur sur quels points de repère vous vous êtes arrêté avant la construction.
• Échouez fort. Si ffmpeg est manquant, dites-le et affichez la commande d'installation pour la plateforme de l'utilisateur.