j-guide-video

Vidéo d'instructions illustrée (disposition guide)

Une étape du document = une scène. Chaque phrase de la narration déclenche des actions : attraper un outil, verser, ouvrir, taper, assembler. Le rendu graphique, l'audio et l'exportation sont effectués en Swift (CoreGraphics, AVFoundation). La CLI jgv orchestre l'ensemble : script, audio, sous-titres, images fixes et vidéo.

• <skill> est le répertoire de ce SKILL.md (${CLAUDE_SKILL_DIR}. Si indisponible, utiliser ${CLAUDE_PLUGIN_ROOT}/.claude/skills/j-guide-video pour les plugins, sinon ~/.claude/skills/j-guide-video ou .claude/skills/j-guide-video selon ce qui existe).
• La commande jgv ci-dessous fait référence à <skill>/bin/jgv. Lors de la première utilisation et après chaque mise à jour du skill, la compilation de lui-même et du kit (DSL de rendu et composants) prend quelques dizaines de secondes à quelques minutes. La compilation est mise en cache (~/Library/Caches/j-guide-video/). Le projet vidéo ne contient que les fichiers spécifiques au sujet (script, binding, queues, assets SVG). Le mécanisme est décrit dans reference/environment.md. Si l'utilisateur demande à vider le cache, utilisez jgv clean --stale --dry-run pour afficher ce qui sera supprimé, puis jgv clean --stale ; pour tout effacer, rm -rf ~/Library/Caches/j-guide-video (la reconstruction se fera à la prochaine compilation). Si la variable J_GUIDE_VIDEO_CACHE pointe vers un autre dossier, ne supprimez pas ce dossier racine, uniquement les sous-dossiers build-*, shared-*, projects et avtts (car le dossier peut ne pas être dédié).
• Les arguments et options sont listés via jgv help <sous-commande>. Toute option inconnue génère une erreur.
• <library> est la bibliothèque utilisateur (variable d'environnement J_GUIDE_VIDEO_LIBRARY, par défaut ~/.config/j-guide-video, ou $XDG_CONFIG_HOME/j-guide-video si défini). Elle contient les outils et animations créés lors des vidéos précédentes (dans parts/) et les préférences (defaults.json). Elle persiste après les mises à jour du skill. Détails : reference/library.md

procedure.md ─(jgv new = init・md2script --stubs・tts・timing)→ script.json・queues et binding squelette・audio・timeline・sous-titres・tableau des temps
visuals/bind.swift (dessin et nom des outils/écrans) + cues/<Étape>.cue (actions par phrase) ─(jgv check → jgv dev → jgv render → jgv overview)→ out/video.mp4

Prérequis à vérifier

Environnement d'exécution

• Réservé à Claude Code sur macOS (version compatible avec le dernier Xcode ; testé uniquement sur Apple Silicon, Intel Mac non vérifié). Ne pas exécuter sur Linux, Windows (y compris WSL2), Claude Code via le web, ou Claude.ai. Informer l'utilisateur et arrêter.
• Nécessite le dernier Xcode ou les Command Line Tools (swift, installer via xcode-select --install ; versions anciennes non testées). jgv s'arrête si des outils sont manquants ou obsolètes. Proposer à l'utilisateur de les installer (ne pas exécuter de commandes sudo sans accord). Une connexion réseau est nécessaire uniquement pour la première compilation de jgv.
• La narration utilise par défaut les voix macOS ("voice": "auto" sélectionne la meilleure voix pour la langue du script. Liste : jgv voices).
• Les TTS utilisables en environnement professionnel sont les TTS cloud intégrés et la passerelle command vers n'importe quel exécutable. Les TTS cloud s'activent via une variable d'environnement : google (GOOGLE_TTS_API_KEY ou GOOGLE_APPLICATION_CREDENTIALS pour une clé de compte de service), azure (AZURE_SPEECH_KEY + AZURE_SPEECH_REGION), amazon (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY + AWS_REGION), openai (OPENAI_API_KEY ; déconseillé pour les vidéos à long terme car le modèle sera arrêté le 06/01/2027).
• Les clés et scripts sont fournis par l'utilisateur. Claude ne saisit ni n'affiche les clés API, n'ouvre pas les fichiers de clés de compte de service (GOOGLE_APPLICATION_CREDENTIALS), et n'appelle pas d'API payante sans autorisation.
• Lors de la manipulation d'un projet vidéo créé par un tiers (zip, dépôt externe, script passé via --base), avant d'exécuter jgv, vérifiez avec l'utilisateur le contenu de script.json et script.<langue>.json (tous les scripts passés à jgv tts etc.), notamment la section tts (moteur cloud payant ou commande dans command), et la présence de fichiers Swift dans visuals/, parts/, kit/. Les commandes jgv tts / timing / dev / check / snapshots / still / preview / catalog / render / build-langs (toutes les commandes qui génèrent de l'audio ou exécutent du code visuel) exécutent ces instructions telles quelles.
• Les TTS cloud payants ne sont pas appelés tant que vous n'avez pas explicitement autorisé le projet et le moteur via jgv tts --allow-cloud (la commande jgv tts s'arrête en affichant le nombre de lignes et de caractères). --allow-cloud ne doit être ajouté qu'après avoir informé l'utilisateur du moteur et des coûts, et obtenu son accord. (Les projets créés via jgv new --tts … ou utilisant le moteur défini dans defaults.json de la bibliothèque sont automatiquement autorisés. En cas de reprise d'un projet tiers avec jgv new --base, jgv new s'arrête avant toute création et demande de choisir avec --tts).
• Les détails sur la voix, la vitesse, les réglages de chaque TTS, le disque et le cache sont dans reference/environment.md.

Conditions d'utilisation des vidéos générées

• Voix macOS (par défaut apple) : Selon la licence macOS d'Apple (section « Voices »), les voix système ne peuvent être utilisées que pour créer des œuvres originales à usage personnel et non commercial. Les vidéos exportées sont donc limitées à un usage personnel et non commercial. Elles ne peuvent pas être publiées sur les réseaux sociaux, sites de vidéos, ni utilisées dans un cadre professionnel ou en entreprise (y compris les manuels internes, selon une interprétation stricte de la licence). (Résumé. Se référer à la licence macOS, section « Voices »).
• TTS google / azure / amazon / openai / command : Se conformer aux conditions d'utilisation du TTS concerné. Un TTS utilisable en environnement professionnel permet une publication et une utilisation en entreprise. Si le TTS exige un crédit ou une mention de voix IA, l'ajouter dans le champ credit du fichier script.json.
• Si la demande concerne une publication sur les réseaux sociaux, un site de vidéos, ou une utilisation professionnelle/en entreprise, avant de commencer le travail, informez-en l'utilisateur et proposez de basculer vers un TTS utilisable en environnement professionnel. N'effectuez pas de jugement juridique (conseillez à l'utilisateur de vérifier la licence macOS et les conditions d'utilisation du TTS choisi).

0. Choisir le type de mise en page

Déterminez le type en fonction du sujet et informez-en brièvement l'utilisateur (demandez confirmation en cas de doute). Indiquez également le répertoire de création du projet (le <dir> de l'étape 2) à ce moment-là.

Type	--layout	Apparence	Sujets adaptés	Exemples (examples/)
Pièce	guide (défaut)	Même personnage debout dans une pièce, manipulant des outils. Gros plan via carte agrandie pour les détails	Boissons, tâches ménagères, entretien d'appareils – tout ce qui implique une personne manipulant des objets	room-microwave-rice, room-mug-wash
Opération d'écran	guide-screen	Pas de personnage. Écran de téléphone/navigateur manipulé par tap/clic/saisie. Note contextuelle à droite, zone hors focus assombrie	Procédures d'utilisation d'applications et services web	screen-alarm (téléphone)
Vue de dessus	guide-topdown	Vue du dessus d'un plan de travail, deux mains entrant par le bas	Cuisine, bricolage, emballage – sujets où les mains sont au centre	topdown-cucumber
Manuel d'assemblage	guide-manual	Papier millimétré blanc, vue isométrique au trait, flèches en pointillés, serrage de vis, liste de pièces	Assemblage de meubles, installation d'appareils, remplacement de pièces	manual-smallbox
Portrait	L'un des types ci-dessus + --vertical	1080×1920. Pour le type « pièce », personnage en haut et carte agrandie toujours visible en bas (testé uniquement pour ce type)	Astuces de vie courtes, recettes, visualisation verticale sur mobile	vertical-coffee

Même si plusieurs langues sont nécessaires, commencez par terminer une version dans une langue, puis ajoutez les langues supplémentaires à l'étape 6.

1. Préparer le document de procédure

Synthétisez le texte de l'utilisateur dans le format Markdown suivant et enregistrez-le dans <dir>/procedure.md (si le document est déjà dans ce format, utilisez-le tel quel).

# Comment préparer un café filtre
## Préparez-vous [prepare]
Préparez une tasse, un sachet de café filtre et une bouilloire. Portez l'eau à ébullition et laissez-la refroidir à environ quatre-vingt-dix degrés Celsius.
## Ouvrez le sachet [open]
Tenez le sachet à deux mains, déchirez la bande supérieure le long de la ligne marquée. Ouvrez-le doucement pour éviter de renverser le café.

• # Titre, ## Nom de l'étape [tag], le texte est lu tel quel. Le tag est optionnel et donne le nom du visuel (par exemple open → Open). Le tag doit être composé uniquement de caractères alphanumériques commençant par une lettre, plus - et _. Sinon, il est ignoré et le visuel s'appelle Step01, etc.
• Les listes à puces ou numérotées : chaque élément est une phrase. Les marqueurs de lien, d'emphase ou de code en ligne sont retirés pour la lecture (les balises HTML, commentaires et blocs de code ne sont pas lus. Les <Chevrons> autour des noms de touches comme <Enter> sont conservés). En japonais et chinois, les retours à la ligne sont aussi des séparateurs de phrase (une ligne se terminant par une virgule de lecture continue à la ligne suivante). En anglais etc., une ligne vide sépare les paragraphes. Ajoutez un point en fin de phrase si nécessaire. Les tableaux (lignes | … |) et blocs de code ne sont pas lus (un avertissement est émis si vous retirez un tableau).
• Idéalement 4 à 8 étapes, chaque étape contient 1 à 3 phrases. Une phrase = une unité d'animation ; une virgule (,) = une sous-unité. Écrivez donc des phrases où l'action (« quoi → comment ») est clairement décomposée en segments de lecture (exemple : « Dépliez les accroches papier, placez-les sur le bord de votre tasse. »).
• Les temps d'attente réels (infusion, séchage…) sont supposés raccourcis dans la vidéo.
• Si le document utilisateur est libre (notes, modes d'emploi), reformatez-le selon les critères de reference/rewriting.md pour obtenir une procédure structurée.

2. Créer le projet et le convertir en script

jgv new <dir> --kicker "RITUEL QUOTIDIEN / GUIDE DU CAFÉ" --layout guide

jgv new effectue en une seule commande : création du projet (jgv init), génération des scripts et queues squelette (jgv md2script procedure.md -o script.json --stubs visuals), création de l'audio et de la timeline (jgv tts), et affichage du tableau des temps des queues (jgv timing – numéro ligne.phrase et secondes depuis le début de l'étape). Le fichier de procédure utilisé est <dir>/procedure.md (s'il se trouve ailleurs, utilisez jgv new <dir> <chemin> pour le copier). Les options sont les mêmes que pour jgv md2script. Exécutez les commandes suivantes après un cd <dir>.

• <dir> est celui spécifié par l'utilisateur s'il existe. Sinon, créez-le sans demander, en dehors du répertoire du skill et du dépôt qui le contient (par exemple ~/Movies/jgv/<sujet>). Dans les deux cas, avant la création (lors de l'étape 0 où vous communiquez le type de mise en page), indiquez le chemin complet (exemple : « Je vais créer le projet dans ~/Movies/jgv/massage-epaules. Dites-moi si vous préférez un autre emplacement. »). Créer dans le répertoire courant peut générer des fichiers out/ et .jgv/ dans le dépôt.
• --layout est le type choisi à l'étape 0. Pour le format portrait, ajoutez --vertical. --kicker est le nom de la série affiché en haut à gauche.
• Les options --presenter (apparence du personnage), la relation avec defaults.json, le TTS cloud (--tts), l'absence de texte (--no-text etc.), et la migration de projets d'anciens formats (jgv migrate) sont décrites dans reference/options.md#options-de-jgv-new. Si defaults.json contient déjà des valeurs pour kicker / layout, n'ajoutez --kicker / --layout que si l'utilisateur a explicitement spécifié une valeur différente de celle de l'étape 0.
• Si jgv new échoue : la commande nettoie ses propres créations et resta l'état initial (les fichiers préexistants sont conservés). Corrigez la cause et relancez la même commande jgv new (en cas d'interruption, consultez le dépannage dans reference/tips.md).

Fichiers générés (le projet est opérationnel dès cette étape) : script.json, cues/<Visuel>.cue pour chaque étape (avec en tête les numéros ligne.phrase et une annotation textuelle), visuals/<Visuel>.swift (une ligne appelant la queue – ne pas toucher), visuals/bind.swift (squelette de binding), .jgv/timeline.json, out/subtitles.srt.

Correction des lectures japonaises

• Pour le japonais, le champ speak de chaque ligne dans script.json permet de faciliter la lecture des chiffres, lettres et mots difficiles. Pour indiquer une lecture, utilisez le katakana (le hiragana peut se fondre dans le contexte et créer des ambiguïtés. Par exemple, «食欲やはいせつぶつ» pourrait être mal segmenté en «や／は／いせつ…» alors que ハイセツブツ est sans ambiguïté).
• Utilisez jgv yomi pour afficher la lecture mot par mot et les avertissements. Corrigez les lectures qui ne correspondent pas à l'intention. jgv yomi utilise l'analyse macOS indépendamment du moteur TTS, et sert donc d'indication pour les TTS cloud (la correction en katakana fonctionne avec tous les moteurs). (Pour les types d'avertissements et la méthode de correction, voir reference/tips.md#lectures-japonaises).
• Après avoir modifié speak, exécutez jgv tts (ne relit que les lignes modifiées) puis jgv timing (réaffiche le tableau des temps).
• Si l'utilisateur signale des erreurs de lecture, après correction, demandez à l'étape 7 s'il faut ajouter ces corrections au champ readings de defaults.json de la bibliothèque.

3. Définir les outils et les écrans (binding)

Pour chaque étape, déterminez ce qui est montré (outils, appareils, écrans), leur emplacement et les points de contact. Écrivez ces informations dans visuals/bind.swift (le squelette est créé par jgv new) sous forme de binding. C'est un fichier unique pour toutes les étapes. Consultez la syntaxe dans reference/cue.md section « binding ».

• Avant d'écrire, lisez au moins un exemple complet du même type de mise en page (choisissez parmi la liste dans examples/README.md, lisez son visuals/bind.swift et ses cues/*.cue. Inspirez-vous-en pour les mouvements similaires et le placement des outils).
• Utilisez en priorité les pièces du kit et les composants du projet dans parts/ (et de la bibliothèque). Consultez l'apparence via la lecture de reference/props-catalog.png, la liste complète dans reference/visual-kit.md section « Outils ». Pour les arguments et points de préhension (ex : KETTLE_PARTS), utilisez jgv api bouilloire (recherche par nom, nom japonais, description). Utilisez jgv api seul pour la liste des noms. N'effectuez pas de grep sur les sources du kit.
• Si un outil n'existe pas, dessinez-le dans visuals/props.swift selon les règles de reference/prop-style.md et vérifiez l'aperçu avec PROPS_PREVIEW via jgv preview. Les SVG fournis par l'utilisateur peuvent être placés dans assets/ et utilisés avec Svg("nom") (voir visual-kit.md section « Assets SVG »).
• Les positions par défaut et échelles des outils doivent être définies comme des constantes nommées (ex : let MW = Pt(1080, GUIDE.counterY) ; pour le portrait, LAYOUT_PORTRAIT.counterY). Cela permet de ne modifier qu'un seul endroit.
• Placez les outils/objets manipulés par les mains du personnage à proximité de celui-ci (pour une scène large, dans la zone x ≈ 1150). jgv check émet un avertissement si la main est trop éloignée.
• Les étapes « Ingrédients », « Remarques », « Avant/Après », « Résumé » peuvent utiliser les types de scène du kit (PrepareItems, NoteCards, BeforeAfter, SummaryList) dans la syntaxe du binding.
• Les points essentiels d'apparence par type sont dans reference/implementation.md section « Points clés par type ».

4. Écrire les mouvements des étapes avec les queues

Pour chaque étape, écrivez cues/<Visuel>.cue. Les numéros de temps ligne.phrase sont donnés par les annotations en tête du squelette (ex : # 0.0 Riz surgelé, 0.1 dans son film plastique…) et par le tableau des temps de jgv new / jgv timing. La syntaxe est décrite dans reference/cue.md. Pour les mouvements similaires, inspirez-vous des queues des exemples du même type (examples/). Les queues étant courtes (quelques lignes à une dizaine de lignes), ne créez pas de sous-agent pour les étapes ; écrivez toutes les étapes à la suite dans l'agent principal.

init <Load
0.0+.3 H>mw.handle~.45
0.0+.35 mw.open=0~.6
0.2+.45 P mw.start;mw.on=1~.2;mw.disp=cd 2:00 0:[email protected];timer timer [email protected]
1.1+.7 H>dish.gripL~.4;dish.in=0
1.1+.77 dish@PLATE~.5;steam dish.top

• Par phrase, écrivez une ligne pour chaque action « quoi → comment » (déclenchez le mouvement au moment où la phrase est lue). Les temps d'attente sont représentés par un minuteur circulaire (timer) et une annotation « Temps d'attente raccourci ».
• Pour les mains (H>, C>, P), l'instant indiqué est celui où la main arrive. Pour les autres, c'est l'instant de début. Pour synchroniser les valeurs avec les mouvements de main, décalez la valeur de la durée du mouvement de main avant.
• Les étapes suivantes commencent par init <étape précédente (elles héritent de l'état final). Si vous souhaitez laisser la carte agrandie ouverte entre deux étapes, utilisez card.exit=0 dans l'étape précédente et card.enter=0 dans l'étape suivante.
• Les détails fins (ouvrir, verser, frotter, tordre) sont montrés via la carte agrandie (card, C>). Le personnage pointe avec la main gauche de la carte (H>gesture). La dernière étape montre le résultat final + une vérification (check) + une ambiance (vapeur, scintillement).
• Évitez les plans statiques : vapeur, ondulations (wave), ronds dans l'eau, etc. Pendant la narration, quelque chose doit toujours bouger.

cd <dir> && jgv check

Corrigez les queues et le binding jusqu'à ce qu'il n'y ait plus de lignes commençant par ! (erreurs : nom incorrect, main trop éloignée, lâcher un objet en cours de déplacement, mouvement 0,5 seconde avant la fin, chevauchement de texte ou de cadre, etc.). Les lignes H / C affichent un tableau temporel des mains (de quelle seconde à quelle seconde, d'où vers où). Les lignes S1→S2 montrent les différences aux frontières entre étapes (seules les variations intentionnelles doivent apparaître). Les corrections de queue ne nécessitent pas de recompilation, vous pouvez vérifier immédiatement. Voir l'interprétation des lignes et la correction dans cue.md section « jgv check ».

Pour les mouvements spéciaux non réalisables par les queues, écrivez du Swift dans la fonction de dessin du binding et contrôlez-le par des valeurs passées dans la queue (voir cue.md section « Écriture en Swift »). Vous pouvez également utiliser le workflow alternatif (storyboard → implémentation parallèle par sous-agent) pour les visuels écrits entièrement en Swift (reference/implementation.md).

5. Vérification complète → Exportation

cd <dir> && jgv dev

jgv dev effectue une vérification complète en une seule étape : jgv tts (relit uniquement les lignes modifiées) → compilation → jgv check (s'arrête en cas de lignes !) → jgv snapshots pour les seules étapes modifiées depuis le dernier jgv dev.

• Les erreurs de compilation (binding, etc.) sont affichées avec le nom du fichier et le numéro de ligne (ex : visuals/bind.swift:12:5: error: …).
• La dernière ligne Images à vérifier: liste les images à lire. Pour la première fois, après modification des fichiers Swift, assets/, des couleurs, ou si toutes les étapes sont modifiées : affichez out/snapshots/sheet.png global. Si seules les queues sont modifiées, affichez out/snapshots/scene-N/sheet.png pour les étapes concernées (y compris celles qui héritent via init <étape précédente). La modification du script change la durée de la vidéo et déplace la barre de progression, ce qui provoque généralement une regénération complète. Pour tout regénérer, utilisez jgv dev --all.
• Ouvrez impérativement les images listées dans Images à vérifier: via la commande Read, corrigez et relancez jgv dev. (Attention : si seules certaines étapes sont regénérées, le fichier global out/snapshots/sheet.png reste celui de la version précédente.)
• Pour les détails invisibles sur la vue d'ensemble (pointillés, annotations textuelles, position des mains et des poignées), lisez les images par plan (moitié de la résolution vidéo ; le nom du fichier correspond au numéro de ligne affiché lors de l'exportation, ex. 03.png. Avec jgv snapshots --scene=N --phrases, une image par phrase, ex. 02-04.png. Note : jgv dev n'a pas l'option --phrases).

Ce qu'il faut vérifier sur les images :

• Les mains touchent-elles bien les poignées des outils ? Les outils flottent-ils ou se chevauchent-ils ?
• Le contenu de la phrase correspond-il à l'action visuelle ? (ex. pour une phrase « déchirer la bande », la bande est-elle effectivement déchirée ?)
• Les étiquettes des sous-étapes et annotations dans la carte agrandie sont-elles lisibles ? Les chevauchements de texte, d'annotations ou de cadres sont signalés par jgv check sur des lignes ! début-fin s:. Vérifiez également sur l'image les chevauchements entre objets, les objets dessinés en double, et que le dessin du binding ne chevauche pas la barre de sous-titres ou les titres (non détecté par check). En mode --no-text / --no-notes, vérifiez qu'aucune explication n'apparaît.

Si tout est correct, exportez, puis créez la page de résumé :

cd <dir> && jgv render && jgv overview

out/overview.html regroupe sur une seule page (à ouvrir dans un navigateur) la narration de chaque étape, les fichiers visuels, les images fixes et les assets SVG. Communiquez les emplacements de out/video.mp4, out/subtitles.srt et out/overview.html. Envoyez la vidéo si l'environnement le permet. Passez ensuite à l'étape 7.

Les réglages de couleurs, de voix, les traitements en cas d'erreur, et des exemples concrets implémentés en Swift (demo/ du dépôt) sont dans reference/tips.md.

6. Créer des versions multilingues

Une fois la version dans la première langue terminée, ajoutez les fichiers script.<langue>.json selon les instructions de reference/multilang.md, puis utilisez jgv build-langs pour exporter toutes les langues en une seule commande (la vidéo est commune, seuls le script et les textes à l'écran sont changés).

7. Sauvegarder dans la bibliothèque

Après l'exportation, proposez à l'utilisateur de sauvegarder dans la bibliothèque les éléments suivants (s'ils peuvent être réutilisés pour d'autres sujets) :

• Outils et animations créés pour cette vidéo (visuals/props.swift, shared.swift, les méthodes de dessin des outils dans le binding).
• Paramètres choisis par l'utilisateur comme préférence (couleurs, voix, vitesse, etc. – à l'exception du kicker spécifique au sujet).
• Corrections de lecture japonaise signalées par l'utilisateur (readings).

S'il n'y a aucun nouvel élément ou s'ils sont déjà identiques à la bibliothèque, ne demandez pas. Pour la sauvegarde, suivez la procédure décrite dans reference/library.md section « Sauvegarder après la réalisation d'une vidéo » : copiez les éléments dans <library>/parts/ et mettez à jour <library>/defaults.json. Cela réduira le travail de dessin et de configuration pour les vidéos futures.