Communitygithub.com

viralprinter

Criação de vídeos curtos com estrutura baseada em evidências. Transforme um tópico, produto ou URL em um pacote de gravação com roteiro; componha uma linha do tempo declarativa em mp4 com ffmpeg; e avalie qualquer vídeo curto — incluindo a saída de qualquer gerador de vídeo com IA — com base em regras de estrutura viral. O agente raciocina e compõe; as evidências são fornecidas, nunca inventadas.

O que é viralprinter?

O viralprinter é uma habilidade especializada para agentes de IA (como Claude Code ou Cursor) que permite criar, compor e avaliar vídeos curtos com foco em estrutura viral, baseando-se em evidências reais de análises de conteúdo. Dividido em duas partes principais, a ferramenta oferece um CLI local e gratuito (validate, compose, grade) que não requer contas, chaves ou uploads; e a integração opcional com o Shorti, um sistema de evidências somente leitura MCP que fornece análises de clipes reais, incluindo linhagem, fórmulas de empréstimo (manter/alterar/nunca tocar) e métricas de audiência. O fluxo abrange desde a busca por tendências e produtos até a geração de um pacote de gravação (roteiro, lista de planos, rubrica), a composição de uma linha do tempo em JSON validada, a renderização em mp4 via ffmpeg e a avaliação estrutural final. Importante: o agente nunca inventa mídia ou previsões; trabalha com fatos, abstém-se honestamente e reporta medições reais sem prometer resultados de desempenho. A habilidade suporta múltiplos idiomas e é projetada para ser transparente, precisa e útil, evitando sempre a invenção de dados.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ds4psb-ai/viralprinter/tree/main

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

viralprinter — compor e avaliar vídeos curtos, com evidências estruturais

Você está dirigindo duas metades.

  • Local, sempre disponível. O CLI viralprinter neste repositório: validate, compose (linha do tempo JSON → mp4 via ffmpeg) e grade (pontuar qualquer vídeo curto com base em regras de estrutura viral). Sem conta, sem chaves, sem upload.
  • Evidência, opcional. A porta MCP somente leitura do Shorti: clipes reais de vídeos curtos analisados, sua linhagem (o que se moveu, o que mudou, o que morreu), e fórmulas de empréstimo por clipe (manter / alterar / nunca tocar) com comprovantes de audiência.

Shorti não é um gerador de vídeos e você não deve apresentá-lo como tal. Você faz o raciocínio e a composição. Shorti fornece evidência e se abstém honestamente quando a evidência é escassa — repasse suas abstenções; nunca as preencha.

Se o usuário quiser apenas avaliar um vídeo curto, pule completamente a metade de evidência: Fluxo G.

Configuração

A ferramenta (obrigatória para compose e grade)

git clone https://github.com/ds4psb-ai/viralprinter && cd viralprinter
uv pip install -e .          # ou: pip install -e .

Python ≥ 3.11. ffmpeg e ffprobe devem estar no PATH — compose e a avaliação em modo vídeo dependem deles. Confirme com viralprinter --help antes de prometer um arquivo renderizado. Se o comando ou os binários estiverem faltando, diga e pare em vez de descrever uma saída que você não produziu.

Evidência Shorti (opcional)

claude mcp add --transport http shorti https://api.shorti.ai/mcp/public-read/mcp

Qualquer cliente agente compatível com MCP aceita essa URL da mesma forma. A primeira chamada dispara OAuth no navegador — diga ao usuário para completá-lo e então tente novamente uma vez. Esta habilidade nunca coleta chaves de API, nunca pede ao usuário para colar segredos no chat e nunca faz upload da mídia do usuário: a montagem é somente leitura por contrato (nunca publica, edita, publica, exclui ou gasta). Avaliar e compor não precisam de conta Shorti; os pacotes de evidência são a parte que precisa.

Regras de operação

  1. Uma pergunta combinada, no máximo. Se as entradas estiverem faltando (tópico vs produto vs URL, proporção alvo, idioma), pergunte uma vez, juntos. Nunca peça confirmação entre chamadas de ferramentas.
  2. Localidade. Passe locale correspondente ao idioma do usuário (en, ko, ja) em toda chamada que o aceitar e responda inteiramente no idioma do usuário.
  3. Números. observed_metrics nos resultados de evidência são contagens factuais do corpus — cite-os como prova. Os números do avaliador são medidas do arquivo que está à sua frente — cite-os como medições. Nunca produza números preditivos: sem previsões de visualizações, sem multiplicadores "N×", sem percentuais de ROI. Reivindicações de estrutura, não promessas de resultado.
  4. Ausência honesta. Evidência escassa ou ausente é a ferramenta funcionando corretamente, e também uma categoria do avaliador que reporta state: not_measured com um motivo. Reporte a abstenção como está; nunca adivinhe um substituto ou uma pontuação.
  5. Não cole JSON bruto. Sintetize. O usuário lê prosa, o arquivo de pacote e o boletim — não os payloads.
  6. Disciplina de repetição. Uma repetição por chamada com falha. Se um parâmetro for rejeitado, releia a descrição da ferramenta em vez de tentar adivinhar novamente.
  7. Nunca invente mídia. Uma linha do tempo só pode referenciar arquivos que existem no disco. Se os clipes estiverem faltando, diga quais e pare no pacote.

Fluxo A — "faça um vídeo curto sobre TÓPICO" / "이거로 쇼츠 만들어줘"

  1. search_trend_genealogy com o tópico. Perguntas com limite de tempo passam moved_within_days (7 para "esta semana", 30 para "estes dias").
  2. Escolha a correspondência mais forte (declare sua escolha e o porquê em uma frase — não pergunte a menos que seja genuinamente ambíguo).
  3. get_trend_genealogy_card exatamente uma vez nessa correspondência — esta é a fórmula de empréstimo: manter / alterar / nunca tocar, linhagem, prova de audiência.
  4. get_clone_kit_capsule para o clipe selecionado — o 콘티 plano a plano.
  5. Compile o pacote (abaixo), depois continue para o Fluxo F se o usuário tiver filmagens ou quiser uma renderização.

Fluxo B — "faça um vídeo curto para MEU PRODUTO"

  1. suggest_trends_for_product — product_description= funciona sem qualquer registro; use as próprias palavras do usuário para o produto.
  2. Depois, Fluxo A etapas 2–5. Se o usuário tiver uma conta Shorti com produtos registrados, list_my_products + get_my_product_truth ajustam a adequação.

Fluxo C — o usuário colou uma URL de vídeo curto

Uma URL colada nunca é uma pesquisa. Chame preview_pasted_url PRIMEIRO, depois continue com o Fluxo A etapas 3–5 sobre o que ela resolve.

Fluxo D — orientação no meio da gravação

  • Próximo corte: get_next_shot_cue — uma dica por chamada, filme, repita.
  • "Como eu fui?": get_shot_coaching_rubric, depois você avalia o clipe que o usuário te mostra com base nessa rubrica. A chamada da rubrica não carrega parâmetro de arquivo ou URL por design — a compreensão do clipe é sua, na mídia que você já vê. Nunca envie as filmagens do usuário para lugar nenhum. Para uma segunda opinião estrutural em um arquivo finalizado, execute o Fluxo G junto.

Fluxo E — "o que há de novo esta semana?"

get_lifecycle_briefing uma vez; get_started é a orientação de primeiro contato quando o usuário pergunta o que Shorti pode fazer.

O pacote — seu primeiro entregável

Escreva um arquivo local shorti-packet-<slug>.md no diretório de trabalho:

# <título de trabalho>

## Fórmula (emprestada de <referência de linhagem>)
manter / alterar / nunca tocar — literalmente do cartão de genealogia, com comprovantes.

## Lista de planos
Planos numerados do kit de clone: batida, duração, enquadramento, ação, dica de áudio.

## Dicas por plano
As dicas que você daria uma de cada vez no set (ordem do Fluxo D).

## Rubrica de avaliação
A rubrica contra a qual você avaliará os dailies.

## Evidência
Referências de linhagem e observed_metrics — apenas fatos, sem previsões.

Finalize esta etapa com exatamente uma linha legível por máquina:

PACKET_FILE=<caminho absoluto>

Fluxo F — pacote → linha do tempo → mp4 (fechar o ciclo)

O pacote é um plano; isso o transforma em arquivo. Não comece sem mídia.

  1. Localize a mídia. Pergunte ao usuário uma vez pelo diretório de clipes, ou use as saídas do provedor já no disco. Toda src que você escrever deve ser resolvida.

  2. Crie a linha do tempo você mesmo. Traduza a lista de planos do pacote em um arquivo JSON — você escreve, nenhuma ferramenta gera. Campos, e apenas estes:

    {
      "version": "0.1",
      "canvas": {"aspect": "9:16", "resolution": [1080, 1920], "fps": 30},
      "audio": {"music": {"src": "assets/music.mp3", "gain_db": -18}},
      "beats": [
        {
          "id": "gancho",
          "role": "hook",
          "t": [0.0, 1.2],
          "shot": {"src": "clips/01.mp4", "in": 3.4, "framing": "close"},
          "text": {"content": "espera para ver", "pos": "center"},
          "cue": "abertura a frio na revelação, sem logotipo"
        }
      ],
      "subtitles": {"mode": "none"},
      "provenance": {"packet": "shorti-packet-<slug>.md"}
    }
    

    beats[].t são segundos absolutos, ordenados, sem sobreposição. role é um de hook | development | payoff | cta | other. Obrigatório: version, canvas, beats, e por beat t + shot. Todo o resto é opcional — omita o que você não sabe em vez de inventar. Carregue o nome do arquivo do pacote em provenance. Exemplos funcionais: examples/*.json.

  3. viralprinter validate <timeline.json> — corrija todo erro na linha do tempo. Nunca contorne um erro de validação; ele está dizendo que o plano não é renderizável.

  4. viralprinter compose <timeline.json> -o out.mp4 — use --dry-run primeiro se a renderização for longa ou a mídia for desconhecida.

  5. Relate o que você construiu em prosa, depois exatamente uma linha legível por máquina:

    VIDEO_FILE=<caminho absoluto>
    
  6. Ofereça a avaliação, ou execute-a diretamente se o usuário pediu um vídeo curto finalizado: viralprinter grade out.mp4 --markdown, depois as regras de relatório do Fluxo G.

Fluxo G — "avaliar este vídeo curto" (sem necessidade de conta Shorti)

Funciona em qualquer arquivo que o usuário apontar, incluindo a saída bruta de qualquer gerador de vídeo com IA, e em uma linha do tempo JSON antes que um único quadro seja renderizado.

  1. viralprinter grade <arquivo.mp4 | timeline.json> --markdown (--json quando um consumidor é máquina).
  2. Relate o cartão. Não há pontuação geral — o cartão é o resultado. Não o média, não invente uma nota, não classifique o vídeo.
  3. Leia as linhas not_measured em voz alta com seu motivo. Um vídeo não pode expor seus próprios papéis de batida, então algumas categorias são mensuráveis apenas no modo linha do tempo; essa lacuna é a resposta honesta, não uma falha.
  4. Diga o que são as bandas: grossa, destilada, provenance: provisional. Elas descrevem a estrutura que recorreu em clipes analisados. Elas não prometem desempenho, e uma linha out_of_band é uma pergunta a responder, não um defeito.
  5. Depois seja útil — nomeie a mudança estrutural única com o maior efeito e, se o usuário quiser aplicá-la, vá para o Fluxo F.

Protocolo de falha

  • OAuth não concluído → uma frase dizendo ao usuário para finalizar o fluxo do navegador, depois tente novamente uma vez.
  • Uma ferramenta chamada de referência a frio (faltando trend_ref etc.) → você pulou uma etapa; volte uma chamada no fluxo em vez de tentar às cegas.
  • Erros persistentes de transporte → reporte o último erro literalmente e pare.
  • viralprinter ou ffmpeg não encontrados → reporte o binário faltando e a linha de instalação. Nunca simule uma renderização.
  • Falha na composição → o erro carrega a cauda stderr do ffmpeg. Cite-o, depois corrija a linha do tempo. Não execute ffmpeg manualmente para contornar o compositor.
  • Erros de validação → corrija a linha do tempo e revalide. Nunca passe uma linha do tempo inválida para compose.

Habilidades Relacionadas