movie-still-finder

Movie Still Finder

Transforme "Preciso de um frame de duas pessoas sentadas em silêncio após uma discussão" em um arquivo de imagem real e com origem. Qualquer agente de IA, qualquer sistema operacional, sem credenciais.

1. Leia isto primeiro: o que é realmente possível

Não existe nenhuma API pública gratuita que aceite uma frase em linguagem natural e retorne o quadro exato do filme, especialmente um com legendas de diálogo embutidas. Buscar essa "bala de prata" é perda de tempo. O que funciona é um pipeline, onde o agente orquestra e um modelo com capacidade de visão escolhe o quadro:

request -> fact-check -> choose source -> batch-download candidates
        -> numbered contact sheet -> VISUAL frame picking -> high-res original
        -> crop subtitles / composite subtitle -> visual re-check
        -> delivery + source manifest

Duas consequências inegociáveis:

• A etapa de visão não pode ser pulada. Adivinhar um quadro apenas pelo nome do arquivo ou texto falha. Mostre a folha de contato a um modelo com capacidade de visão (ou ao humano).
• Verifique os fatos primeiro. "Fatos" amplamente repetidos sobre filmes geralmente estão errados (veja references/fact-check.md). Verifique a fala / cena / episódio antes de pesquisar.

2. Início rápido (perfil mínimo, o padrão)

pip install -r requirements.txt
python scripts/still.py probe                       # quais fontes estão acessíveis agora
python scripts/still.py grab --out ./work \
  --page "https://movie-screencaps.com/avatar-2009/page/114" \
  --image-referer "https://movie-screencaps.com/" \
  --limit 40
# -> ./work/candidates/*.jpg, ./work/contact_1.jpg, ./work/manifest.json
# Mostre contact_1.jpg a um modelo de visão, anote o número vencedor, então:
python scripts/still.py sheet ./work/candidates     # regenera uma folha numerada
python scripts/still.py crop ./work/candidates/p1_02.jpg --bottom 100 -o ./work/clean.jpg
python scripts/still.py deliver ./work --picks examples/sample-picks.json \
  --profile profiles/minimal.json --out ./delivery

Sempre execute probe primeiro: a disponibilidade das fontes varia. Para uma execução totalmente offline, veja a seção D de examples/quickstart.md. --image-referer normalmente é a raiz do site, não a URL do artigo.

Para uma fala de diálogo, quote fornece o filme + timestamp em milissegundos:

python scripts/still.py quote "I see you" --title Avatar

Walkthrough completo: examples/quickstart.md. Referência de comandos: scripts/still.py --help.

3. Decida a rota antes de tocar na rede

Solicitação	Primeira escolha	Fallback
Cena / clima ("silêncio após uma briga", "duas pessoas de costas")	Artigo editorial com stills legendados, ou frames curados do FilmGrab (grab)	Galeria quadro a quadro + seleção visual
Uma fala citada / "o quadro onde X diz Y"	quote → timestamp → galeria de quadros → subtitle (rotular como compositado)	Captura de tela com legendas nativas de um artigo editorial
Precisa de arte de capa ampla, limpa e sem legendas	Frames curados do FilmGrab	crop os 95-100 px inferiores de uma captura de visualização
Usuário tem arquivos de vídeo locais	Pesquisa semântica local opcional, veja references/optional-adapters.md	—
Meme / 梗圖 em vez de um still	Apêndice opcional, references/meme-optional.md	—

Execute probe primeiro. É gratuito, não requer login e informa quais fontes estão com 403 / inacessíveis no seu ambiente, para que você não tente novamente um host morto.

4. Regras que valem para todo agente

1. Sem credenciais. Não peça chaves de API, não faça login em nome do usuário, não burle paywalls ou proteções antibot. Um 403 significa "mude de fonte", registrado no log de execução.
2. Baixe apenas URLs que foram realmente retornadas. Nunca invente uma URL de imagem. Uma página acessível não significa que seu CDN de imagens seja acessível: verifique uma imagem antes de confiar em toda uma galeria. Se as imagens retornarem 403 após uma correção de Referer, mude de fonte — não continue variando cabeçalhos.
3. Registre a proveniência. Cada imagem entregue precisa de página de origem, URL direta da imagem, título/ano do filme e se alguma legenda foi cortada ou compositada. grab escreve isso em manifest.json automaticamente.
4. Marque legendas compositadas. Se você adicionar uma legenda que não estava no quadro original, informe isso na legenda. Nunca apresente como um quadro nativo.
5. Verifique, não assuma, a resolução (>= 1000 px de largura por padrão) e abra o arquivo final com um visualizador antes de entregar.
6. Respeite o perfil. O comportamento além do acima (seleção com intervenção humana, entrega em pastas duplas, verificação de fatos obrigatória, pré-visualização de corte de capa) é controlado por profiles/*.json. Não ative regras extras silenciosamente.

5. Perfis (comportamento opcional)

O padrão profiles/minimal.json é um pipeline simples e de propósito geral: encontre candidatos, escolha um, entregue com proveniência. Todo o resto é opt-in.

python scripts/still.py rules --profile profiles/editorial-wechat.json
python scripts/still.py deliver ./work --picks picks.json \
  --profile profiles/editorial-wechat.json --out ./delivery

editorial-wechat.json agrupa o fluxo de trabalho de um editor humano: pré-visualizações numeradas e seleção humana (nunca finalizar automaticamente), entrega em pastas duplas com zero exclusão de candidatos, verificação de fatos obrigatória, anotação obrigatória de legendas/fonte e uma pré-visualização de corte de capa 2,35:1. Veja profiles/README.md para o esquema completo.

6. Índice de referências (divulgação progressiva)

Leia apenas o que a etapa atual precisa.

Arquivo	Leia quando
references/workflow.md	Você precisa do POP completo de ponta a ponta e da lista de verificação de aceitação
references/sources.md	Escolhendo uma fonte, ou uma fonte parou de funcionar
references/pitfalls.md	Algo falhou; contém os hosts conhecidos como mortos e modos exatos de falha
references/image-ops.md	Folhas de contato, corte, composição de legendas, fontes
references/fact-check.md	Qualquer solicitação citando uma fala ou descrevendo uma cena específica
references/delivery.md	Esquema de proveniência, layout de pastas duplas, limite de direitos autorais
references/meme-optional.md	Usuário pediu um meme em vez de um still
references/optional-adapters.md	Biblioteca de vídeo local ou outras ferramentas baseadas em login/CLI

7. Lista de verificação de aceitação

• A fala / cena foi verificada antes da pesquisa
• Uma folha de contato numerada foi examinada por um modelo de visão ou pelo humano
• A imagem final abre corretamente e corresponde à solicitação, não apenas à consulta
• Página de origem + URL direta + filme/ano registrados em manifest.json
• Legendas cortadas / compositadas explicitamente rotuladas
• Largura >= 1000 px (ou o desvio está declarado)
• Hosts mortos e soluções alternativas registrados em vez de repetidos silenciosamente
• Nenhum candidato foi excluído; intermediários mantidos

8. Limites de escopo

Esta skill encontra e prepara imagens. Ela não publica nada, edita o manuscrito do usuário, decide a capa final em nome do usuário (a menos que o perfil diga que o humano já escolheu) ou concede qualquer direito de redistribuir stills de filmes. Veja references/delivery.md para o limite de direitos autorais.