Freedom Video Generation Studio

O que Freedom Video Generation Studio faz?

Construa vídeos reproduzíveis a partir de um tópico, roteiro, prompt ou exemplo em Python. A renderização com Manim é obrigatória para cenas determinísticas e animação de código ou diagramas; um modelo de vídeo em nuvem configurado pode adicionar ou gerar outras imagens. Mantenha o fluxo de trabalho portátil entre Codex, Claude, Gemini, OpenClaw, Hermes, DeepSeek, Kimi, WorkBuddy ou um script Python comum.

Separe as Duas Camadas de Provedor

• Use um provedor de agente apenas para escrever o plano de aula, narração, legendas, prompts e código fonte Manim/Python. Pontos de extremidade de chat compatíveis com OpenAI podem ser usados para provedores como DeepSeek, Kimi ou Hermes.
• Use um provedor de vídeo apenas para gerar ou aprimorar clipes de vídeo. Nunca envie um job de vídeo para um endpoint de chat-completions.
• Trate o Agnes Video 2.5 Flash como um padrão opcional, não uma dependência rígida.
• Leia references/provider-config.md antes de configurar ou chamar qualquer provedor.

Fluxo de Trabalho Obrigatório

1. Crie um diretório de projeto de saída. Mantenha fonte, áudio, legendas, renderizações e logs dentro dele.

2. Antes de escrever ou renderizar a lição, execute:

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

   Esta etapa é obrigatória. Ela encontra ou instala o Manim em <PROJETO_SAIDA>/.venv-manim, verifica a versão e realiza uma renderização de teste real. Pare se falhar. Use o caminho do executável Manim impresso pelo script para renderizações posteriores.

3. Quando a narração for necessária, execute esta configuração obrigatória antes de gerá-la:

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

   Ele instala a pilha Kokoro Chinesa fixada em <PROJETO_SAIDA>/.venv-kokoro, preserva a revisão solicitada do kokoro-tts-zh em .vendor, baixa o modelo/voz selecionado no primeiro uso e sintetiza um WAV de teste real. Pare se qualquer etapa falhar. Leia references/audio-config.md para vozes e comandos de narração.

4. Produza um plano de aula cronometrado. Para cada cena, especifique narração, código na tela, animação, texto da legenda e duração. Use Manim para conceitos de execução de código, mudanças de estado, ponteiros, traços, diagramas e visuais educacionais determinísticos.

5. Gere a narração completa antes de travar o tempo das cenas. Use scripts/kokoro_narrate.py, padrão para a voz de ensino calorosa zf_032 na velocidade 0.96, mantenha uma voz e uma velocidade moderada constante dentro de uma lição, e ajuste os visuais/legendas ao WAV medido e seu manifesto.

6. Renderize um rascunho do Manim e verifique se sua duração medida, tamanho do quadro, limites do texto, destaque de código e transições correspondem ao plano de narração.

7. Chame um provedor de vídeo em nuvem apenas quando ele melhorar materialmente a lição. Execute a verificação de segurança abaixo antes de cada job faturável.

8. Monte o vídeo final e verifique áudio, sincronia das legendas, legibilidade do código, duração e saída reproduzível.

Política de Fonte de Narração

• Para cada vídeo narrado, use uma voz em chinês fornecida pela família de modelos kokoro-tts-zh integrada.
• Nunca use say do macOS, SAPI do Windows, síntese de fala do navegador ou outra voz do sistema operacional como fallback automático.
• Se a instalação do Kokoro, download do modelo, carregamento da voz ou síntese falhar, pare e relate a falha. Não substitua silenciosamente por uma voz mecânica.
• Kokoro fornece vozes predefinidas; não clona um falante enviado arbitrariamente. O caminho de clonagem do repositório vinculado depende de um submódulo StableTTS separado e pesos de modelo que não são autocontidos ou verificados por esta Skill. Para uma solicitação de clonagem, exija um backend de clonagem configurado e validado separadamente, além da confirmação de que o usuário tem permissão para usar a voz.

Pré-Voo de Cobrança Obrigatório

Antes de cada solicitação de vídeo em nuvem:

1. Consulte o endpoint de preço atual do provedor ou a fonte oficial de preços atual.
2. Consulte a cota/créditos da conta através do endpoint de cota configurado.
3. Calcule o custo máximo esperado usando duração, resolução, modelo e preços do provedor solicitados.
4. Compare com VIDEO_MAX_COST_PER_TASK e os créditos disponíveis.
5. Registre o resultado do pré-voo em <PROJETO_SAIDA>/usage/video-usage.jsonl.

Não envie o job se o preço ou a cota forem desconhecidos, o endpoint não puder ser verificado, os créditos forem insuficientes ou o custo máximo for excedido. Um provedor que anuncia um nível gratuito não prova que a solicitação atual é gratuita.

Regras de Repetição e Polling

• Nunca repita indefinidamente.
• Use VIDEO_MAX_POLLS e VIDEO_POLL_INTERVAL_SECONDS para jobs assíncronos.
• Repita falhas de rede transitórias ou HTTP 429/5xx no máximo VIDEO_MAX_RETRIES vezes com backoff exponencial limitado.
• Para erros de fila cheia, capacidade cheia, crédito insuficiente, autenticação, validação ou política de preços, pare imediatamente, a menos que o provedor forneça explicitamente um curto Retry-After e o orçamento de repetição configurado permita uma repetição.
• Nunca crie um job substituto apenas porque o polling de status falhou; primeiro recupere o job original por ID.

Livro-Razão de Uso

Acrescente um objeto JSON por pré-voo e chamada de provedor a <PROJETO_SAIDA>/usage/video-usage.jsonl. Nunca armazene chaves de API ou cabeçalhos de autorização. Inclua:

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

Se o provedor não retornar o custo real, defina actual_cost como null e cost_known como false; não registre silenciosamente zero. Resuma o total de chamadas, duração gerada, custo conhecido e chamadas com custo desconhecido no final.

Contrato de Saída

Entregue o vídeo final, mais o código fonte editável do Manim, o WAV de narração do Kokoro e seu manifesto, arquivos de legenda, modelo de configuração seguro para o provedor, comando de renderização e livro-razão de uso. Indique a voz/modelo/velocidade do Kokoro usados e declare claramente quando nenhuma API de vídeo em nuvem foi chamada ou quando o custo não pôde ser verificado.

Não exponha segredos no código fonte, logs, prompts, histórico do shell, capturas de tela ou arquivos .env commitados. Use variáveis de ambiente e forneça apenas modelos .env.example.