brewed-ops/spatial-film

Spatial Film

Prouvé de bout en bout sur un film produit de 60 secondes (7 scènes, 5 travailleurs en une vague, chaque raccord exact à l'image, vérification propre, 1080p60 en 4 minutes 19 secondes). Le film.json du modèle contient les barres réelles de ce film et sa feuille de repère comme exemple concret.

<skill> = le dossier de cette compétence (le répertoire où se trouve ce SKILL.md). Exécutez chaque script depuis la racine du projet film. python ci-dessous = la commande Python enregistrée par la vérification de configuration d'explainer-kit dans ~/.talking-explainer/config.json (py -3.12 sur Windows, python3 sur macOS).

Ce dont vous avez besoin

• Node 20+, ffmpeg + ffprobe dans le PATH, Python 3.10+ avec numpy et Pillow.
• Les compétences HyperFrames : npx hyperframes skills update general-video hyperframes-animation media-use (constructeur de paquets, plans + carte d'animation, aide musicale). La CLI elle-même est épinglée par projet et s'exécute via npx.
• Playwright pour le pré-rendu des surfaces : npm i -D playwright dans le dossier du film (ou définissez PLAYWRIGHT_PATH).
• Optionnel, pour la musique sourcée : un compte HeyGen - exécutez npx hyperframes auth login une fois dans votre terminal. Sans cela, apportez votre propre piste et commencez la phase 4 à music-analyze.py.
• Une machine avec GPU pour le rendu final (le rendu fonctionne aussi sur le chemin logiciel, environ 15 fois plus lent).

Comment utiliser cette compétence sans gaspiller de contexte

• Chargez UN seul fichier de référence à la fois, lorsque sa phase commence. Ne les préchargez jamais tous.
• Les scripts sont le code éprouvé. Exécutez-les ; ne régénérez jamais leur logique en ligne.
• La session principale ne lit jamais un fichier de scène entier (20-60 Ko). Évaluez les scènes par des planches contact ; corrigez avec grep -n plus un patch exact.
• Les travailleurs reçoivent des CHEMINS de fichier, pas du contenu collé. storyboard.html (60 Ko+) est parcouru par identifiant de cellule, jamais lu en entier.
• Lisez d'abord une planche contact ; ouvrez des PNGs individuels uniquement pour vérifier un détail.

Phases (chacune se termine sur une porte - ne passez pas à la suivante avant qu'elle ne soit franchie)

#	Phase	Chargement	Porte
0	Échafaudage : node <skill>/scripts/new-film.mjs <dir> --name <slug>	-	le dossier contient film.json, frame.md, kit, docs modèles
1	Réception, BRIEF, STORYBOARD, feuille d'esquisse	references/storyboard.md	« go » explicite de l'utilisateur enregistré sous ## Verrouillé
2	frame.md, kit, surfaces pré-rendues	references/surfaces.md (+ platform-canvases.md uniquement si GHL/n8n/Zapier apparaissent)	pas de {{ dans frame.md ; chaque PNG de capture examiné
3	Test de harnais, paquets, travailleurs parallèles	references/workers.md	chaque scène : lint 0 erreurs, planche contact correspond à son bloc
4	Musique + SFX (exécuté pendant que les travailleurs construisent)	references/audio.md	fond sonore au BPM natif, mesure 0 sur un temps fort ; repères dans film.json
5	Assemblage, vérification, raccords, rendu, livraison	references/verify-ship.md	vérification réussie, seam-check tout PASS, rendu hardware-gpu vérifié

Routez via /hyperframes -> /general-video pour les étapes d'intention et de revue d'esquisse (cette compétence fournit la forme du projet, le contrat, les scripts et les portes ; general-video fournit le constructeur de paquets et le rôle de travailleur).

Fichiers

Chemin	Quoi
template/	Squelette de projet : film.json (barres de scène, BPM, bgm, SFX, repères - l'UNIQUE source de timing), frame.md (contrat de vérité de conception avec champs à remplir), BRIEF.md, STORYBOARD.md, assets/kit.css (kit de film de base), assets/fonts/ (Poppins 500/700 + OFL), references/worker-brief.md, references/scene-starter.html (squelette de scène propre au lint), references/snippets.html, package.json (hyperframes 0.8.117 épinglé).
surfaces/	Reconstructions HTML prêtes des canvas GHL, n8n et Zapier + une longue page marketing (données fictives Northwind Dental), platform.css, sprite.svg, jobs.json.
scripts/new-film.mjs	Échafauder un projet à partir du modèle.
scripts/capture-surfaces.cjs	Rendre src/captures/*.html -> assets/captures/*.png en 2x (jobs.json).
scripts/measure-surface.cjs	Boîtes 1x des éléments sur une surface, pour des cibles d'annotation/découpage exactes.
scripts/make-harness.py, scripts/test-scene.mjs	Projets de test isolés par scène ; lint + snapshotter une scène.
scripts/music-search.mjs, sfx-search.mjs	Catalogue HeyGen via l'aide REST de media-use (sûr sous Windows).
scripts/music-analyze.py, music-bars.py	Tempo numpy-only + énergie par mesure (pas besoin de librosa).
scripts/bgm-cut.py	Couper le fond sonore sur les lignes de mesure, raccorder sa propre outro, fondus ; --b répète pour boucler un fond sous un film plus long.
scripts/assemble.py	film.json -> index.html (emplacements de scène sur la grille de mesures, bgm, SFX avec durées + pistes).
scripts/seam-check.py	Vérifie pixel par pixel chaque raccord (avant / au / après la coupe) et la boucle (image 0 vs dernière).
scripts/render-final.mjs	Rendu CLI avec --browser-gpu, enregistré dans un fichier, mode GPU + ffprobe vérifiés, puis flash-scan.py.
scripts/flash-scan.py	Chaque image d'un rendu : une image différente de ses deux voisines (un élément affiché pendant 1/60s) = un bug.
scripts/encode-web.mjs	Encodage Web (H.264 CRF 21, faststart, AAC ou --silent) + image d'affiche.
scripts/blink-fit.py, scripts/build-presenter.py	Films narrés : superpositions de clignement pour les poses de feuille (--band = bande oculaire) ; la superposition du présentateur à partir de sa piste, avec synchronisation labiale lorsque le mascotte a mouth-fit.json.
scripts/el-tts.py, el-words.py, el-music.py	Films narrés via ElevenLabs (clé dans env EL, jamais sur disque) : candidats vocaux depuis SCRIPT.md, timings de mots Scribe, fond sonore généré.
scripts/seam-diff.py	Diff des raccords avec la boîte du présentateur masquée (films narrés).
scripts/fromto-scan.py	Pré-rendu : signale les propriétés fromTo FROM-only que les travailleurs de rendu (recherches en milieu de scène) n'appliquent jamais. 0 hits avant chaque rendu.
scripts/patch_exact.py	Recherche/remplacement exact, sûr CRLF, pour les corrections de scène scriptées (affirme une correspondance chacune).
scripts/selftest.mjs	Preuve de bout en bout que la compétence fonctionne sur cette machine. Doit afficher PASS.

Films narrés (une voix off + un présentateur à l'écran)

Prouvé sur un explicatif narré « API vs Webhook » (83s, vertical et paysage, voix clonée, présentateur mascotte, 10 scènes par 5 travailleurs). Les règles de film musical ci-dessus s'appliquent toujours sauf là où celles-ci les remplacent :

• Candidats vocaux d'abord. EL=<key> python <skill>/scripts/el-tts.py . eric=<voice_id> michelle=<voice_id> lit les lignes indentées de SCRIPT.md et écrit un MP3 par voix dans src/audio/voice-candidates/ (clé depuis l'env uniquement, jamais sur disque). Laissez l'utilisateur choisir à l'oreille, puis transcrivez uniquement le choix.
• La narration est l'horloge. Temps de mots : EL=<key> python <skill>/scripts/el-words.py <voice.mp3> src/timing/voice-words.json (ElevenLabs Scribe - pas de modèle local, nécessite une clé), ou faster-whisper avec word_timestamps (langue définie, VAD activé ; transcribe.py d'explainer-kit, gratuit et local). Gardez le JSON des mots dans src/timing/. Dans film.json, définissez `