fish-video-skill

---

name: fish-video-skill description: Crie um Short, Reel, TikTok, vídeo para YouTube ou LinkedIn premium e pronto para upload sobre qualquer assunto. Use quando alguém pedir um vídeo, explicador, promo, tour de produto ou app, tutorial com gravação de tela, Short motivacional ou "um vídeo como este" (link de referência). Começa com uma entrevista única e rigorosa (tópico, plataformas, estilo, cores, voz, música, SFX, assets, gravação de tela, chaves de API), depois nunca mais pergunta até a revisão final. Pesquisa tendências e fatos, analisa vídeos de referência, coleta assets reais licenciados, grava a tela com zooms e sons de clique, e renderiza motion graphics determinísticos com câmera 3D: colagem de papel, tipo cinético, diagramas neon, metáforas brilhantes, whiteboards. Adiciona voz natural, mixagem otimizada para alto-falantes de celular e legendas dinâmicas, executa QA e auto-revisão, empacota vídeos, thumbnails, títulos, descrições, tags e créditos, e só limpa com permissão. versão: 2.1.0 licença: MIT autor: ImuTechz compatibilidade: Python 3.10+ (3.12 recomendado), Node 18+, um navegador Chromium (Brave/Chrome/Edge/Chromium), ffmpeg (empacotado via npm). Windows, macOS, Linux. Chaves opcionais ELEVENLABS_API_KEY, PEXELS_API_KEY, PIXABAY_API_KEY, FREESOUND_API_KEY, YOUTUBE_API_KEY; cada uma tem uma alternativa sem chave.

Fish Video Skill v2

Você faz um vídeo a partir de uma conversa. Ele deve atingir a qualidade dos melhores Shorts analisados em análises de referência:

• algo novo na tela a cada ~1 s
• assets reais com profundidade (textura, sombras de contato, brilho)
• tipo com contraste de palavra-herói 3×
• transições objeto-como-portal
• um swish que aterrissa antes de cada movimento, risers que terminam em revelações, impactos em cortes rápidos
• uma voz que se destaca sobre um fundo musical audível

Um slideshow com voz genérica é uma falha, mesmo que o QA passe.

Roteador: carregue o guia quando chegar à tarefa

Leia apenas o que a etapa atual precisa:

• O usuário deu apenas uma palavra, quer ideias de tópico, ou você está escrevendo o roteiro → tópico para vídeo
• Escolhendo um estilo, paleta ou aparência → receitas de estilo, config/styles.yaml
• Uma ideia precisa de explicação, ou escolher cores por clima → design de diagrama
• Escrevendo qualquer cena → catálogo de cenas, incluindo regras de Movimento e Câmera
• Qualquer coisa sobre música, SFX ou níveis, ou "Não consigo ouvir a música no meu celular" → design de som
• Escolhendo ou dirigindo uma voz → direção de voz
• Legendas e tipo → legendas e tipografia
• Um site ou app na tela → captura de tour de site
• Um vídeo de referência para combinar → análises de referência, análise de vídeo de referência, análise de tendências
• Tamanhos e limites de plataforma → especificações de plataforma
• Qual ferramenta open-source usar → guia de campo

Fluxo de trabalho inegociável

0 doctor ─▶ 1 ENTREVISTA (todas as perguntas, uma vez) ─▶ confirmar ─▶ 2 pesquisa + tendências + referências (paralelo)
  ─▶ 3 assets + captura de tela + voz (paralelo) ─▶ 4 storyboard (você escreve cada palavra) ─▶ gate
  ─▶ 5 stills (aparência) ─▶ 6 render ─▶ 7 loop de QA + REVISÃO (corrigir, re-renderizar, repetir) ─▶ 8 empacotar ─▶ 9 revisão final ─▶ 10 limpar (perguntar)

Regras:

• Uma entrevista, no início. Todas as perguntas que precisam do usuário são feitas na etapa 1, incluindo voz e tom, cores, as etapas da tela, chaves de API (com como obter cada uma) e os extras opcionais para instalar. Após fishvideo interview <dir> --confirm, você não faz perguntas. Decida a partir das respostas e da receita de estilo. Entre em contato com o usuário novamente apenas nestes casos:

  • (a) uma parada opcional que ele escolheu em checkpoints
  • (b) uma gravação de desktop que ele deve realizar; ele concordou com isso na entrevista, e você diz exatamente quando começar
  • (c) a revisão final
  • (d) permissão para limpar

  Se o usuário depois disser algo diferente, siga o usuário.

• Nunca escreva um roteiro antes da entrevista ser confirmada. fishvideo script, all e render completo recusam até que fishvideo gate passe.

• Nunca envie texto de template. O scaffold é um esqueleto de TODOs. Você escreve cada palavra na tela e cada linha de narração fresca para este vídeo, então o gate bloqueia TODOs, frases feitas v1 ("X, explicado", "em 60 segundos", "Obrigado por assistir") e qualquer linha copiada de examples/. Exemplos mostram estrutura, nunca conteúdo.

• Explicadores ganham um diagrama. Qualquer vídeo com goal: explain precisa de pelo menos um mecanismo de cena diagram, whiteboard, neonline ou split-revelação. Uma lista de tópicos não é uma explicação.

Etapa 0: doctor

A configuração (primeira vez apenas) está em README.md: npm install, um venv, e pip install -r requirements.txt. Então execute:

.venv/Scripts/python scripts/fishvideo.py doctor --keys      # Windows (macOS/Linux: .venv/bin/python)

Observe quais chaves e extras estão faltando. Pergunte exatamente sobre eles na rodada 8 da entrevista.

Configuração para o melhor resultado (faça isso, não pule):

• Instale os extras você mesmo. Se doctor mostrar um extra faltando, instale-o no venv do skill sem fazer o usuário fazer isso: pip install "rembg[cpu]" (recortes), pip install kokoro soundfile (vozes naturais locais) e pip install faster-whisper (alinha a narração do próprio usuário). Também execute fishvideo assets sfx-pack uma vez se a biblioteca de SFX estiver faltando. Diga ao usuário em uma linha o que você está instalando e por quê. Só pule um extra que o usuário recusar na rodada 8.
• Peça as chaves de API. Elas são opcionais: tudo funciona sem elas através das alternativas gratuitas. Elas dão o melhor resultado: ElevenLabs dá as vozes mais naturais, Pexels/Pixabay dão as fotos e vídeos de stock mais comuns, Freesound dá o maior número de SFX, e a YouTube Data API dá os gráficos de tendências. Na rodada 8, peça as que importam para este vídeo, diga como obter cada uma (links de inscrição gratuita estão em doctor --keys), e aceite "não" ou "depois" sem insistir. Faça isso apenas na entrevista, nunca depois que a criação começou.

Etapa 1: a entrevista (rigorosa)

fishvideo new projects/<slug> --prompt "<a solicitação do usuário, literal>"
fishvideo interview projects/<slug>            # JSON: as perguntas abertas, agrupadas em 8 rodadas

O banco de perguntas é config/interview.yaml. Ele tem 8 rodadas e cerca de 30 perguntas:

Rodada	Abrange
1	propósito
2	forma e estilo
3	cores, tipo, textura
4	voz, entrega, música, SFX
5	assets reais e gravação de tela
6	conteúdo, fatos, CTA, idioma
7	legendas, thumbnail, aprovações
8	chaves de API e extras

Apenas uma palavra ou uma área? Antes da rodada 1, gere 5 ângulos em tendência: yt suggest, yt search --recent-days 30 e trends (subagentes haiku, em paralelo), seguindo tópico para vídeo. Ofereça-os como a pergunta topic. O ângulo escolhido direciona tudo depois disso.

Como perguntar:

• Pergunte uma rodada por chamada AskUserQuestion (até 4 perguntas), usando as opções exatamente como listadas. Opções recomendadas vêm primeiro. "Outro" está sempre disponível.
• Perguntas de texto livre (free_text: true) vão em uma mensagem normal para aquela rodada, junto com a chamada de múltipla escolha da rodada.
• Pule uma pergunta apenas quando o prompt já a responder inequivocamente (from_prompt mostra o que foi detectado), e registre-a de qualquer forma.
• Registre cada resposta: fishvideo interview <dir> --set style=paper-collage --set platforms='["shorts"]'. As respostas mapeiam para brief.yaml: a paleta vai para brand.colors, o clima para a partitura e o tempo, a voz e a entrega para a configuração de voz e cadeia de pós-processamento, e o estilo para textura, ritmo e motivo.
• Voz: após as rodadas 4 e 6 (uma vez que o idioma e a entrega são conhecidos), execute fishvideo voices <dir> --audition. Dê ao usuário os caminhos dos arquivos em build/auditions/ para que ele possa reproduzi-los, e deixe-o escolher. Isso ainda faz parte da entrevista.
• Chaves: ofereça apenas as chaves faltantes que importam para as respostas deles. Explique como obter cada uma (o texto no banco) e o que acontece sem ela. Se eles colarem chaves, registre-as com --set keys_paste=.... As chaves vão para o .env gitignorado do skill e nunca são ecoadas, registradas ou commitadas. Se eles escolherem extras, instale-os no venv agora (pip install "rembg[cpu]", kokoro soundfile, faster-whisper).
• Finalmente, leia fishvideo interview <dir> --summary de volta para o usuário. Peça um simples "sim, vá em frente", então execute --confirm.

Etapa 2: pesquisa, tendências e referências (executadas em paralelo)

Gere estes como subagentes paralelos. Roteamento de modelo: haiku para buscas de busca e consulta, sonnet para análise e código de rotina, e você (opus) para o roteiro, storyboard, julgamento de design e revisão final. Instrua cada agente com o caminho do projeto e o arquivo de saída exato que ele deve produzir. Subagentes podem não conseguir escrever arquivos de relatório; então eles retornam o texto e você o salva.

Tarefa	Comando	Agente
Fatos e fontes	pesquisa na web, depois fishvideo research <dir> --url ... → research/facts.md	haiku
Tendências	fishvideo trends <dir> --topic "<tópico>" --region <IN/US> → research/trends.md (fórmulas de título, tags, hooks, duração ideal do que está ranqueando agora)	haiku
Consultas no YouTube	fishvideo yt search "<q>" -n 20 [--recent-days 30], yt info, yt subs, yt suggest	haiku
Análise de referência (cada link que o usuário deu, mais 1–2 exemplos em tendência no estilo escolhido)	fishvideo yt download <url> --purpose reference --project <dir>, depois fishvideo dissect <dir>/reference/<file>.mp4 --out <dir>/reference/dissect --fps 4 [--vtt subs.vtt]. Leia cada planilha, o espectrograma e timeline.md, depois escreva reference/analysis.md com as nove seções de análise de vídeo de referência	sonnet (visão)

A partir das análises, extraia números: taxa de mudança, tempo e nível do swish, dB da voz sobre a música, profundidade de ducking, volume, estilo de legenda. Escreva-os em brief.yaml → match: para que o storyboard e a mixagem possam segui-los. Copie o ofício, nunca o conteúdo.

Etapa 3: assets, tela e voz (executadas em paralelo)

Assets reais (quando assets.policy é mixed):

• Pesquise: fishvideo assets search <dir> "<substantivo>" --kind photo|video|music|sfx [--providers wikimedia,pexels]. Abra as prévias em assets/_candidates/ e olhe para elas.
• Baixe o que você escolher: fishvideo assets get <dir> <ids>. Cada arquivo é registrado em assets/credits.json com sua licença.
• Faça recortes: fishvideo assets cutout in.jpg out.png (rembg com isnet-general-use; nunca o modelo padrão não comercial).
• Prepare b-roll: fishvideo assets clip <dir> <file> <clip_id> --start S --dur S dá quadros para a cena footage.
• Obtenha uma seção CC-BY do YouTube: fishvideo yt clip <url> <start> <end> <dest> --project <dir>. Ele recusa vídeos não CC.
• Licenças permitidas: CC0, PD, licenças Pexels/Pixabay, CC-BY e CC-BY-SA (com crédito). Nunca NC ou ND. Nunca um vídeo do YouTube não CC, filmagens de um vídeo de referência, um logotipo que você redesenha, ou a semelhança de uma pessoa real de forma enganosa.

Tela:

• website: liste as tomadas sob captures: e execute fishvideo capture <dir>. Ele filma em modo somente leitura em tempo virtual.
• desktop: fishvideo screenrec record <dir> <shot> --seconds N [--window "Título"] [--scale 2]. Antes de começar, diga ao usuário exatamente quais etapas realizar. F8 solta uma marca e F9 para.
• files: fishvideo screenrec import <dir> <shot> recording.mp4.

Todos os três produzem a mesma pasta de captura. A cena tour (frame: inset) adiciona o cursor brilhante, ondulações de clique e SFX de clique, um zoom de 1,6–2× no cursor, um spotlight e cartões STEP. Grave na escala 2 para que os zooms permaneçam nítidos.

Música:

• Uma faixa da biblioteca: assets search <dir> "<brief.music.search>" --kind music, depois assets get, e coloque o arquivo em assets/music/.
• Ou deixe a partitura sintetizada. Defina music.source: synth para forçá-la.

SFX: execute fishvideo assets sfx-pack uma vez (Kenney CC0). Adicione mais com assets search --kind sfx (Freesound CC0) em assets/sfx/<tipo-de-cue>/.

Voz: escreva a narração (etapa 4), depois execute fishvideo voice <dir>. Re-execute o storyboard para que as cenas sejam re-temporizadas para os clipes reais. Se o usuário gravou sua própria narração, execute fishvideo voiceover <dir> recording.wav: ele alinha a gravação ao roteiro com faster-whisper e a corta por linha.

Emoção: dê a cada cena um mood: (curious, tense, urgent, excited, warm, serious, reflective, triumphant, neutral). Ele define velocidade e tom por linha, e estilo no ElevenLabs. A pontuação molda a entrega em todos os motores: ... pausa, ? e ! elevam, frases curtas golpeiam. Varie o clima entre os ritmos: um tom plano por 40 segundos é a reclamação de "voz genérica". Sessões de silêncio dentro de uma linha são cortadas automaticamente (pacing.max_word_gap).

Temporização da música: para uma faixa da biblioteca, execute fishvideo beats <track>. Defina o bpm do storyboard para seu tempo e music.offset para que uma batida ou a queda caia na sua maior revelação.

Gravações de tela: execute fishvideo screenrec tighten <dir> <shot> para acelerar trechos ociosos. Nunca faça o espectador esperar por um spinner de carregamento.

Etapa 4: storyboard (você escreve)

Execute fishvideo script <dir>. Ele gera storyboard.yaml a partir da receita de estilo (config/styles.yaml, receitas de estilo) como um esqueleto de ritmo cheio de TODOs. Suas temporizações são placeholders. Depois escreva-o corretamente, nesta ordem:

1. Substitua cada TODO: cópia, params e narração. A tabela no topo do catálogo de cenas lista os params necessários.
2. Escreva brief.punch se for engraçado.
3. Ajuste a temporização: calcule o tempo total da narração, distribua o tempo de tela (1–2 segundos para takes de stock, 2–4 para tomadas longas, 5+ para diagramas e momentos), e certifique-se de que a mudança na tela nunca exceda 2 segundos. Mova a voz para cenas adjacentes se necessário.
4. Execute fishvideo storyboard <dir> --render para verificar a coerência. O gate verifica:
   • Nenhum TODO em copy, params ou narration
   • Nenhuma frase de exemplo (verifique examples/)
   • Nenhum bloco de voz genérico (qualquer linha usada >2 vezes)
   • Nenhuma cena com duração >8s sem um motivo
   • Nenhum explicador sem diagrama
   • Nenhum parâmetro de cena ausente
5. Execute fishvideo gate <dir>. Se falhar, corrija. Se passar, você está pronto.

Etapa 5: stills (aparência)

Execute fishvideo stills <dir>. A câmera salva uma imagem por cena em stills/. Abra o álbum e examine:

• Cada still tem textura, profundidade e contraste?
• O enquadramento funciona nos dois formatos (9:16 e 16:9)?
• Os cortes de recorte e as bordas estão limpos?
• A marca é consistente?

Ajuste: fishvideo stills <dir> --scene <id> --param brightness=0.8. Re-execute até que cada still pareça profissional.

Etapa 6: render

fishvideo render <dir> --quality 4k

Isso:

• Compõe todas as cenas com a câmera 3D e transições
• Mixa a faixa de voz com a música e SFX (ducking, equalização, e um compressor programado para alto-falantes de celular)
• Queima as legendas
• Produz dois arquivos: build/<slug>-vertical.mp4 e build/<slug>-horizontal.mp4

O duração de renderização depende da complexidade. Cenas com diagramas e partículas podem levar mais tempo.

Etapa 7: QA e revisão (loop)

Execute fishvideo qa <dir>. A especificação de QA está em config/qa-spec.yaml. O relatório de QA está em build/qa-report.md. Verifica:

• Nível de áudio: LKFS entre -14 e -10 (Short/Reel/TikTok) ou -16 a -12 (YouTube/LinkedIn). A altura do pico verdadeiro é <= -1 dBTP.
• Relação voz-música: voz em -8 dBFS pico, música em -18 dBFS RMS. O ducking mergulha a música em -6 dB durante a fala.
• Contraste de vídeo: histograma com pico no quartil superior; sem esmagamento de pretos ou estouro de realces.
• Taxa de quadros e resolução: 30 fps sólidos, 1920×1080 ou 3840×2160.
• Profundidade visual: cada cena tem um plano de fundo/meio/fundo.
• Velocidade das legendas: cada legenda fica visível pelo tempo suficiente para ser lida (pelo menos 1,5 s para frases curtas, 2,5 s para 3–4 palavras). Tempo mínimo da palavra na música: o BPM.
• Consistência: sem mudanças abruptas de tom, cor ou layout.

Se falhar, corrija: fishvideo edit <dir> --scene 4 --param subtitle.speed=fast. Re-renderize: fishvideo render <dir> --scene 4. E execute fishvideo qa <dir> novamente. Continue até que todos os testes passem.

Revisão do usuário: Pare a revisão do usuário apenas quando a etapa 7 passar. Mostre o still de pré-visualização e o vídeo renderizado. Peça feedback e implemente-o. Não pule isso.

Revisão de consistência: Execute fishvideo qa <dir> --check consistency. Se a pontuação de consistência for <80%, reescreva a cena inconsistente.

Etapa 8: empacotar

Execute fishvideo package <dir>. Cria:

• build/<slug>-vertical.mp4 e build/<slug>-horizontal.mp4
• build/thumbnail-vertical.png e build/thumbnail-horizontal.png
• build/title.txt (3–5 opções no formato da plataforma)
• build/description.txt (com CTAs e links)
• build/tags.txt (30–40 tags no estilo da plataforma)
• build/credits.txt (lista de atribuição de licença de todos os assets)

Etapa 9: revisão final

Peça ao usuário para revisar o pacote inteiro: o vídeo, thumbnail, título, descrição e créditos. Obtenha aprovação explícita.

Etapa 10: limpar (perguntar)

Depois que o usuário disser que sim ou finalizado, pergunte: "Posso limpar os arquivos temporários? (build/, captures/, assets/_candidates/) y/N". Se ele disser sim, execute fishvideo clean <dir> --keep build. Mova o pacote finalizado para a raiz do projeto se o usuário quiser.

Guias de referência

• Tópico para vídeo — Da ideia ao ângulo
• Receitas de estilo — Texturas, tempos, motivos por estilo
• Catálogo de cenas — Todas as construções de cena, layouts de câmera, tipos de transição
• Sound design — Mixagem, níveis, compressão para celular
• Direção de voz — Seleção de voz, emoção, entrega
• Legendas e tipografia — Estilos de legenda, animação, hierarquia
• Captura de tour de site — Imersão, zooms, anotações
• Análises de referência — Análise de vídeos de alto nível
• Análise de vídeo de referência — 9 seções de análise
• Análise de tendências — O que está funcionando agora
• Especificações de plataforma — Tamanhos, durações, limites
• Guia de campo open-source — Ferramentas para alcançar
• Design de diagrama — Diagramas de explicador, whiteboards