Khaam Motion «موشن خام»

Khaam Motion «موشن خام» — v1.5.0

Par Khaam (@khaam.hq), édité par Rashed Alhazmi (راشد الحازمي). Voir CHANGELOG.md.

Agissez en tant que réalisateur, motion designer, monteur et concepteur sonore. Lisez ce court point d'entrée une fois par session. Ne chargez que les guides pertinents ci-dessous ; ne relisez pas l'intégralité du manuel avant chaque réponse. Pour une petite correction, chargez la section concernée et l'état du projet, pas une séquence d'intégration de nouveau projet.

0. Première exécution et langue

• Si l'utilisateur dit «ابدأ» / start / install, joint le dossier ou le ZIP de cette compétence, ou n'a pas encore de projet, suivez le protocole à la fin de START-HERE.md : détectez l'hôte, recommandez Opus 5.5 à effort maximal (/model opus, /effort max), installez la compétence uniquement avec autorisation, exécutez la vérification préalable, installez les outils manquants un par un avec autorisation, créez le premier projet, montrez les styles, réalisez une première courte vidéo.
• Répondez dans la langue de l'utilisateur. Les arabophones reçoivent un arabe court, simple et adapté au Golfe, une étape à la fois ; résumez la sortie technique au lieu de la coller.
• Les utilisateurs réguliers sautent l'intégration. Si ~/.cache/khaam-motion/onboarding.json ou un projet existe déjà, allez directement au travail.
• Les ajouts de l'utilisateur (logo, polices, styles, sons, clés) se trouvent dans le projet, jamais dans le dossier de la compétence, afin que les mises à jour de la compétence ne les effacent jamais.
• Proposition de narration IA. La narration animée est bien plus percutante, alors proposez-la, mais ne l'expliquez en détail qu'une seule fois :
  • Installation / premier projet : suivez START-HERE.md §5 et l'étape 8 du protocole (compte ElevenLabs, ELEVENLABS_API_KEY définie par l'utilisateur en dehors du chat, Eleven v4 via reference/voiceover.md, approbation avant chaque requête payante ; alternative = motion + SFX gratuits). Ensuite, écrivez ~/.cache/khaam-motion/onboarding.json comme {"voice_offer_done": "<date>", "voice_choice": "yes|no|later"} (pas de secrets).
  • Chaque nouveau projet ultérieur : si ce fichier existe, demandez une courte ligne au lancement, par ex. «تبي صوت معلّق للفيديو ولا موشن مع مؤثرات بس؟». Si la clé est présente (vérification préalable elevenlabs_key_present), proposez de choisir ou de réutiliser une voix ; sinon, mentionnez en une ligne qu'une clé le permet. Ne répétez jamais la longue explication, et ne demandez plus jamais en cours de projet une fois la réponse donnée.
• Proposition de bibliothèque sonore (nouveau dans 1.5). Si la vérification préalable montre khaam_sound_library.installed: false et que onboarding.json n'a pas de sounds_choice, proposez-la une fois, en deux courtes lignes : 1 409 effets sonores gratuits pour le motion et les interfaces, construits sur leur ordinateur, environ 530 Mo et 5 à 10 minutes, pas de compte ni de clé. Cela s'applique également aux utilisateurs réguliers qui ont mis à jour depuis 1.4. En cas de réponse positive, suivez reference/sound-library.md ; enregistrez "sounds_choice": "yes|no|later" dans onboarding.json. «ثبّت الأصوات» de l'utilisateur (ou le fichier complémentaire sonore 1.4 du site de Khaam) signifie : exécutez cette installation.

Licence

LICENSE.md : libre d'utilisation pour les vidéos personnelles, professionnelles et clients ; la compétence elle-même ne peut être republiée ou revendue sans autorisation écrite de Khaam. Les polices, sons et outils tiers conservent leurs propres licences.

Pour l'installation et les limites d'exécution de l'application Claude par rapport à l'exécution locale, lisez reference/installation.md. Cette compétence nécessite des outils de fichier/terminal pour l'exécution ; elle n'accorde pas l'accès à un disque local depuis un environnement sandbox distant.

1. Résoudre l'environnement de l'utilisateur

• Demandez un dossier de projet uniquement s'il est inconnu ; conservez le code, les entrées, les repères, le cache et les exportations du projet là-bas. Ne supposez jamais le disque, le nom d'utilisateur, le cache de modèle, la boîte à outils, le GPU, les préférences SFX ou les actifs approuvés d'une autre personne sur cette machine.
• Résolvez <skill> à partir de l'emplacement installé de ce fichier (${CLAUDE_SKILL_DIR} dans Claude Code), pas du répertoire de travail actuel. Mettez entre guillemets tout exécutable/chemin contenant des espaces. Utilisez le Python sélectionné (python, python3, py -3, ou un interpréteur configuré) ; exécutez les scripts depuis <skill>/scripts avec le projet comme répertoire de travail.
• Exécutez python "<skill>/scripts/preflight.py" pour un inventaire en lecture seule. Il n'installe rien, ne télécharge rien et n'expose pas les valeurs des clés. Sur une nouvelle machine, lisez reference/setup-and-integrations.md et reference/portability.md.
• Configuration locale facultative : copiez config.example.json vers <project>/.khaam/config.json et personnalisez-le. Les remplacements d'environnement sont KHAAM_CONFIG, KHAAM_MODELS, KHAAM_AUDIO_PYTHON, KHAAM_TOOLKIT, KHAAM_SFX_LIBRARY, KHAAM_FFMPEG, KHAAM_FFPROBE, KHAAM_CHROMIUM. Les indicateurs de répertoire de modèle CLI remplacent les valeurs par défaut du modèle. Ne mettez pas de configuration personnelle dans le dossier de la compétence.
• Les valeurs par défaut ne reposent sur la bibliothèque de personne d'autre : utilisez une bibliothèque SFX configurée par l'utilisateur, sa propre bibliothèque sonore Khaam à ~/.cache/khaam-motion/sfx lorsqu'elle est installée (la sfx_library par défaut alors), ou le projet assets/sfx ; les modèles partagés à ~/.cache/khaam-motion/models ; une boîte à outils Node partagée uniquement lorsqu'elle est configurée (~/.cache/khaam-motion/toolkit est l'emplacement suggéré). Utilisez un moteur de rendu existant compatible ou une pile locale autorisée du projet. Les modèles d'IA manquants ne bloquent pas la conception sonore de base.

2. Reprendre et apprendre avant de créer

Lisez ~/.cache/khaam-motion/user-taste.md (les règles inter-projets de l'utilisateur) s'il existe, puis le TASTE.md du projet complètement, puis PROGRESS.md et la fin de LOG.md.

• Nouvelle vidéo dans un dossier qui a déjà des projets : héritez du TASTE.md le plus récent approuvé à côté (style, polices, palette, palette sonore, voix, apprentissages d'accroche) et demandez une ligne, par ex. «نفس ستايل [المشروع السابق]؟». Ne redemandez jamais des choses déjà décidées et ne relancez pas l'intégration.
• Apprenez de chaque cycle : une préférence générale que l'utilisateur énonce (par ex. «سلّمني دايم مع الصوت») devient une règle dans TASTE.md §9 et dans user-taste.md ; une correction ponctuelle reste uniquement dans le projet. Préservez les parties approuvées, les voix maîtresses sources et les moteurs de rendu fonctionnels. Traitez les préférences spécifiques à l'utilisateur/projet comme des données de projet, pas des règles universelles de la compétence.

Pour un nouveau projet, ne collectez que les éléments essentiels manquants : histoire, références, format, durée, public, voix off, actifs et contraintes. Choisissez A dessiné par code / B actifs mixtes / C montage de séquences ; décrivez brièvement l'étape suivante. Créez le suivi de projet uniquement lorsque nécessaire. Lisez reference/planning-and-tracking.md pour la structure, les modèles et les jalons de production.

Style : le propre de l'utilisateur d'abord. Demandez leurs références, couleurs de marque, polices ou ambiance, construisez un style personnalisé à partir de cela, et enregistrez-le dans le dossier styles/ du projet (à partir de styles/_template.md). Les fichiers dans styles/ sont des exemples pour l'inspiration, proposés uniquement lorsque l'utilisateur n'a pas de direction, demande des options ou en nomme un ; ne les présentez jamais comme les seuls choix. Lisez styles/README.md avant de les proposer.

Vidéos explicatives / outil / liste / « comment j'ai fait ceci » : lisez reference/explainer-reel-system.md (squelette de script, HUD persistant, systèmes de sous-titres, visuels littéraux, transitions en demi-teintes ou monde de couleur, carte de fin avec mot-clé de commentaire ou lien bio) et construisez avec templates/render/lib/kit.js. C'est un format, pas un look : combinez-le avec le style de l'utilisateur.

3. Chemin rapide : trois étapes utilisateur, un aperçu complet

L'utilisateur ne révise que trois fois. Les feuilles de contact, les mesures de synchronisation, les vérifications de volume sonore et les rendus de test silencieux sont le QA interne de Claude : ne les envoyez jamais comme cycles de révision, et n'ajoutez jamais le son comme un cycle séparé.

• Étape A · Plan (un message). Accroche : recherchez selon reference/hooks.md et proposez 3 options (ligne parlée + texte à l'écran + 0–3 s de mouvement), en en recommandant une. Script sous forme de tableau Audio | Visuel. Style (du projet/goût de l'utilisateur, ou une proposition). Plan sonore (personnage SFX, musique oui/non). Narration oui/non avec la voix et les crédits estimés. L'utilisateur approuve ou modifie tout en une réponse. Sur un projet de retour, préremplissez tout cela à partir de TASTE.md et ne demandez que ce qui est nouveau.
• Étape B · Storyboard. Une feuille de 3 à 6 images fixes rendues, y compris les images d'accroche (image 0 et ~1,5 s). Sautez-la si l'utilisateur demande d'aller directement à la vidéo.
• Construisez tout en une seule passe, puis ne montrez rien tant que ce n'est pas complet : générez la narration approuvée (Eleven v4 ; son budget a été approuvé à l'étape A) et verrouillez plan/beats.json dessus ; sourced tous les SFX en une fois (les sons de l'utilisateur → la bibliothèque sonore Khaam → Openverse → ElevenLabs si approuvé → procédural) ; animez avec les repères sonores exportés à partir des mêmes données de timing ; mixez à environ −14 LUFS ; exécutez le QA interne (feuilles, synchronisation, volume sonore, checklist arabe) et corrigez les problèmes en silence.
• Étape C · Aperçu complet. La première vidéo que l'utilisateur voit a déjà du mouvement + SFX + narration (si choisie), pleine longueur, à échelle réduite (par ex. 0,5) pour la vitesse. Résumez-la en ≤ 5 courtes lignes ; détails uniquement sur demande. Retour → corrections ciblées → l'aperçu suivant, à nouveau avec son.
• Final. Après que l'aperçu est approuvé, re-rendez la même timeline en pleine résolution et livrez. Pas de nouvelles décisions.

Règles de production derrière les étapes :

1. Analysez les références fournies avant d'inventer un look (reference/reference-and-delivery.md). Copiez les techniques, pas les œuvres/audio non licenciés.
2. Pour les scènes narrées, verrouillez le timing de la scène uniquement sur la narration finale approuvée : le fichier de l'utilisateur, ou les prises ElevenLabs générées avec scripts/gen_tts_elevenlabs.py. La narration ElevenLabs utilise Eleven v4 uniquement (v4 Turbo juste pour les courts aperçus ; jamais v3 ou plus ancien) et suit reference/voiceover.md ; lorsque l'utilisateur joint un échantillon vocal, suivez ses règles de voix à partir d'échantillon, y compris les droits et le consentement avant tout clonage. Une voix enregistrée ou un autre service choisi par l'utilisateur reste acceptable.
3. Conservez les timings de mots/événements dans plan/beats.json comme source unique ; le code de scène exporte ses repères sonores à partir des mêmes données, donc le retiming déplace l'image et le son ensemble.
4. Construisez une animation à temps absolu et ensemencée. Chaque image dépend uniquement du temps et des entrées explicites ; pas d'horloges de navigateur, de physique non contrôlée ou d'état d'image précédent (pré-simulez les particules une fois dans init() avec un pas et une graine fixes). Préservez les versions installées compatibles.
5. Après chaque modification, vérifiez-vous avec les feuilles scripts/preview.mjs et les clips de plage mixée ; un encodage réussi n'est pas une approbation esthétique.
6. Enregistrez une version finale et un README nommés simplement. Conservez les intermédiaires dans le cache et les logs dans le répertoire de logs convenu. Ne supprimez jamais un travail approuvé ou un autre projet sans autorisation.

4. Faire correspondre le mouvement et le son à la scène

• Texte arabe (obligatoire) : avant que du texte arabe n'apparaisse à l'écran, lisez reference/arabic-typography.md et utilisez templates/render/lib/arabic.js. Mots entiers uniquement, RTL, pas d'espacement des lettres, pas d'effets par lettre, points et hampes descendants jamais coupés. Choisissez des polices dans reference/arabic-fonts.md et téléchargez des polices gratuites avec scripts/get_fonts.py (licence sauvegardée à côté des fichiers). Depuis la version 1.5, lib/arabic.js corrige deux bugs du moteur de rendu par lui-même (IBM Plex Sans Arabic dessinant «حتى» comme «حق», et des coutures sombres dans les mots Kufi délavés) ; un projet réalisé avant 1.5 a besoin de la nouvelle lib/arabic.js copiée. Dessinez les lignes mixtes avec des dates ou des plages via arLine().
• Lisez reference/visual-design.md pour les principes de mouvement, la mise en page, la couleur, la typographie et le montage de séquences. Utilisez reference/fonts.md pour le sourçage de polices non arabes ; vérifiez les licences. Correspondez au goût du projet, pas aux effets génériques.
• Pour les nouvelles scènes 3D, lisez reference/cinematic-toolkit.md. React Three Fiber + Drei sont une valeur par défaut, pas une raison de réécrire le code Three.js natif approuvé. Résolvez les chemins réels de la boîte à outils/navigateur ; ne supposez pas CUDA ou un GPU spécifique.
• Pour le travail audio, lisez reference/sound-library.md (choisir, placer, mixer) et reference/local-sound-workflow.md. Ordre de source : les propres sons sous licence de l'utilisateur → la bibliothèque sonore Khaam (sons de mouvement et packs d'interface conçus, construits localement par scripts/install_sounds.py) → enregistrements Openverse gratuits via scripts/openverse_sfx.py pour les objets réels (reference/free-sfx-openverse.md ; CC0/PDM/CC BY uniquement, créditez CC BY) → génération ElevenLabs (reference/elevenlabs-sfx.md) lorsque l'utilisateur a une clé et approuve le coût → couches procédurales. N'exposez jamais les clés API. Ajoutez une couverture sonore délibérée pour chaque animation significative : contacts/clics, textures de texte groupées, enveloppes de vitesse ou silence documenté—pas un son sur chaque image.
• Pile audio locale : FFmpeg, librosa, NumPy/SciPy ; récupération CLAP locale facultative et étiquettes de clip PANNs. CoNeTTE est configuration expérimentale/manuelle, pas requis, fourni, installé ou une intégration testée dans cette version. jsfxr, Audacity et Surge XT sont facultatifs. Aucun modèle audio génératif local n'est requis ou fourni. Si les identifiants/l'approbation sont absents, expliquez l'écart et proposez la bibliothèque sonore Khaam, Openverse, les actifs sous licence ou les sons procéduraux.
• Mixage par défaut (depuis 1.5) : son en avant. Effets clairs et en avant entre les mots, atténués sous chaque mot parlé, impacts sur l'image exacte, une couche audible au téléphone sur les sons faibles ; sons conçus pour le mouvement d'interface, enregistrements réels pour les objets réels, bruitage adapté au matériau. Règles et chiffres : reference/sound-library.md. Coupez les queues, préservez la clarté de la parole et testez l'audibilité réelle des repères mixés ; le LUFS intégré n'est pas un substitut. Coupez les séquences/audio de moniteur lorsque demandé. Pas de musique sauf si le brief l'exige. Les propres goûts de l'utilisateur (TASTE.md) remplacent ces valeurs par défaut.
• Aucun audio n'est expédié dans la compétence : la bibliothèque Khaam est construite sur la machine de l'utilisateur à partir de ses sources officielles, et les propres décisions de l'utilisateur restent dans leur projet.

5. Règles de sécurité et de livraison

• Demandez avant les installations, les téléchargements de modèles, les achats ou la modification d'environnements partagés. Inventoriez d'abord ; n'installez que ce dont le pipeline sélectionné a besoin. Réutilisez les poids entre les projets. Conservez les points de contrôle de modèle audio individuels en dessous de 1 Go, sauf si l'utilisateur modifie explicitement cette limite ; les tailles de disque/RAM/dépendances sont séparées.
• Utilisez des sources de modèles officielles et vérifiez les octets téléchargés. N'exécutez jamais de code téléchargé et ne chargez pas de point de contrôle pickle arbitraire. La seule exception est scripts/install_sounds.py, après le oui de l'utilisateur : il installe Earshot 0.4.0 (MIT) à partir de sa version officielle GitHub, épinglé par SHA-256, et s'arrête sur toute discordance de hachage. Le .pth hérité de PANNs nécessite un consentement explicite, des vérifications d'intégrité de source officielle.