makunrui80-oss/freedom-video-skill

Freedom Video Generation Studio

Créez des vidéos reproductibles à partir d'un sujet, script, invite, ou exemple Python. Le rendu Manim est obligatoire pour les scènes déterministes et l'animation de code ou de diagrammes ; un modèle vidéo cloud configuré peut ajouter ou générer d'autres séquences. Gardez le workflow portable sur Codex, Claude, Gemini, OpenClaw, Hermes, DeepSeek, Kimi, WorkBuddy, ou un script Python normal.

Séparez les deux couches de fournisseurs

• Utilisez un fournisseur d'agent uniquement pour rédiger le plan de cours, la narration, les sous-titres, les invites, et le source Manim/Python. Les points d'accès de chat compatibles OpenAI peuvent être utilisés pour des fournisseurs comme DeepSeek, Kimi, ou Hermes.
• Utilisez un fournisseur vidéo uniquement pour générer ou améliorer des clips vidéo. N'envoyez jamais un job vidéo vers un point d'accès de chat-complétions.
• Traitez Agnes Video 2.5 Flash comme un défaut optionnel, pas une dépendance dure.
• Lisez references/provider-config.md avant de configurer ou d'appeler un fournisseur.

Workflow requis

1. Créez un répertoire de projet de sortie. Gardez les sources, l'audio, les sous-titres, les rendus et les journaux à l'intérieur.

2. Avant d'écrire ou de rendre la leçon, exécutez :

   python3 scripts/ensure_manim.py --project-root <OUTPUT_PROJECT>
   

   Cette étape est obligatoire. Elle trouve ou installe Manim dans <OUTPUT_PROJECT>/.venv-manim, vérifie la version, et effectue un vrai rendu de test. Arrêtez si elle échoue. Utilisez le chemin de l'exécutable Manim affiché par le script pour les rendus ultérieurs.

3. Lorsque la narration est requise, exécutez cette configuration obligatoire avant de la générer :

   python3 scripts/ensure_kokoro.py --project-root <OUTPUT_PROJECT>
   

   Elle installe la pile Kokoro chinoise épinglée dans <OUTPUT_PROJECT>/.venv-kokoro, préserve la révision source kokoro-tts-zh demandée sous .vendor, télécharge le modèle/voix sélectionné lors de la première utilisation, et synthétise un vrai WAV de test. Arrêtez si une étape échoue. Lisez references/audio-config.md pour les voix et les commandes de narration.

4. Produisez un plan de cours minuté. Pour chaque scène, spécifiez la narration, le code à l'écran, l'animation, le texte du sous-titre, et la durée. Utilisez Manim pour les concepts d'exécution de code, les changements d'état, les pointeurs, les traces, les diagrammes, et les visuels éducatifs déterministes.

5. Générez la narration complète avant de verrouiller le minutage des scènes. Utilisez scripts/kokoro_narrate.py, utilisez par défaut la voix d'enseignement chaleureuse zf_032 à la vitesse 0.96, gardez une seule voix et une vitesse modérée constante dans une leçon, et synchronisez les visuels/sous-titres avec le WAV mesuré et son manifeste.

6. Rendez un brouillon Manim et vérifiez que sa durée mesurée, sa taille d'image, ses limites de texte, la coloration syntaxique et les transitions correspondent au plan de narration.

7. N'appelez un fournisseur vidéo cloud que lorsqu'il améliore substantiellement la leçon. Exécutez la pré-vérification de sécurité ci-dessous avant chaque job facturable.

8. Assemblez la vidéo finale, puis vérifiez l'audio, le minutage des sous-titres, la lisibilité du code, la durée et la sortie lisible.

Politique de source de narration

• Pour chaque vidéo narrée, utilisez une voix chinoise fournie par la famille de modèles kokoro-tts-zh intégrée.
• N'utilisez jamais la commande say de macOS, SAPI de Windows, la synthèse vocale du navigateur, ou une autre voix du système d'exploitation comme solution de repli automatique.
• Si l'installation de Kokoro, le téléchargement du modèle, le chargement de la voix ou la synthèse échouent, arrêtez-vous et signalez l'échec. Ne substituez pas silencieusement une voix mécanique.
• Kokoro fournit des voix prédéfinies ; il ne clone pas un locuteur téléchargé arbitrairement. Le chemin de clonage du dépôt lié dépend d'un sous-module StableTTS séparé et de poids de modèle qui ne sont ni autonomes ni vérifiés par ce Skill. Pour une demande de clonage, exigez un backend de clonage configuré et validé séparément ainsi qu'une confirmation que l'utilisateur a l'autorisation d'utiliser la voix.

Pré-vérification de facturation obligatoire

Avant chaque demande vidéo cloud :

1. Interrogez le point d'accès actuel des prix du fournisseur ou la source de tarification officielle actuelle.
2. Interrogez le quota/crédits du compte via le point d'accès de quota configuré.
3. Calculez le coût maximum attendu en utilisant la durée demandée, la résolution, le modèle et la tarification du fournisseur.
4. Comparez-le avec VIDEO_MAX_COST_PER_TASK et les crédits disponibles.
5. Enregistrez le résultat de la pré-vérification dans <OUTPUT_PROJECT>/usage/video-usage.jsonl.

Ne soumettez pas le job si le prix ou le quota est inconnu, si le point d'accès ne peut pas être vérifié, si les crédits sont insuffisants, ou si le coût maximum serait dépassé. Un fournisseur annonçant un niveau gratuit ne prouve pas que la demande actuelle est gratuite.

Règles de tentatives et d'interrogation

• Ne réessayez jamais indéfiniment.
• Utilisez VIDEO_MAX_POLLS et VIDEO_POLL_INTERVAL_SECONDS pour les jobs asynchrones.
• Réessayez les échecs réseau transitoires ou les erreurs HTTP 429/5xx au maximum VIDEO_MAX_RETRIES fois avec un backoff exponentiel plafonné.
• Pour les erreurs de file d'attente pleine, capacité pleine, crédit insuffisant, authentification, validation, ou politique de prix, arrêtez-vous immédiatement à moins que le fournisseur ne fournisse explicitement un court Retry-After et que le budget de tentatives configuré n'en autorise une.
• Ne créez jamais un job de remplacement simplement parce que l'interrogation de statut a échoué ; récupérez d'abord le job original par son identifiant.

Registre d'utilisation

Ajoutez un objet JSON par pré-vérification et appel de fournisseur dans <OUTPUT_PROJECT>/usage/video-usage.jsonl. Ne stockez jamais de clés API ou d'en-têtes d'autorisation. Incluez :

{"timestamp":"ISO-8601","provider":"nom","model":"id","job_id":"id-ou-null","requested_seconds":10,"actual_seconds":10,"call_count":1,"status":"réussi","price_source":"endpoint-ou-url","estimated_cost":0,"actual_cost":0,"currency":"USD","cost_known":true,"error":null}

Si le fournisseur ne renvoie pas le coût réel, définissez actual_cost sur null et cost_known sur false ; n'enregistrez pas silencieusement zéro. Résumez le nombre total d'appels, la durée générée, le coût connu, et les appels à coût inconnu à la fin.

Contrat de livraison

Livrez la vidéo finale plus le source Manim éditable, le WAV de narration Kokoro et son manifeste, les fichiers de sous-titres, le modèle de configuration sécurisé pour le fournisseur, la commande de rendu, et le registre d'utilisation. Indiquez la voix/modèle/vitesse Kokoro utilisée, et précisez clairement lorsqu'aucune API vidéo cloud n'a été appelée ou lorsque le coût n'a pas pu être vérifié.

N'exposez pas de secrets dans les sources, journaux, invites, historique du shell, captures d'écran, ou fichiers .env commités. Utilisez des variables d'environnement et fournissez uniquement des modèles .env.example.