Communitygithub.com

MelonTse/video-archive-skill

Ajuda o usuário a analisar vídeos localmente, definir metas de compactação, comparar amostras e, após aprovação da qualidade, compactar em lote e arquivar os originais. Destinado à compactação e arquivamento de vídeos caseiros e materiais de arquivo; não é adequado para edição criativa ou conversão de cores HDR/Log não verificada.

O que é video-archive-skill?

Esta skill permite que usuários realizem compactação de vídeos utilizando seu próprio ambiente de IA local, sem depender de serviços de nuvem ou chaves de API externas. Ela primeiro verifica o ambiente local (Python 3.9+, FFmpeg, ffprobe), analisa o material de forma somente leitura para extrair metadados (resolução, taxa de quadros, perfil de cor, faixas de áudio, etc.) e, em seguida, interage com o usuário para definir o objetivo de uso (exibição doméstica, preservação de longo prazo, edição contínua ou compartilhamento), recomendar parâmetros de compactação (encoder, preset, CRF entre 2-3 opções) e gerar amostras para avaliação visual. Após o usuário aprovar explicitamente uma amostra e confirmar o lote, a skill executa a compactação sequencial com FFmpeg, valida a integridade básica (via ffprobe, size/mtime) e orienta o arquivamento do original. A skill é compatível principalmente com macOS (devido ao uso de locks POSIX) e depende de scripts Python que acompanham o pacote. Não faz upload de material, não requer modelos de IA ou API Key, e não substitui verificações rigorosas de qualidade (o teste de integridade automático não é prova de qualidade quadro a quadro). Ela suporta formatos H.264/HEVC com tag BT.709, 4:2:0, 8/10-bit, mas sinaliza manualmente materiais HLG/PQ/HDR, Log e faixas múltiplas para revisão, sem conversão automática para SDR.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MelonTse/video-archive-skill/tree/HEAD/.agents/skills/video-archive

Perguntar na sua IA favorita

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

Documentação

Compactação e Arquivamento de Vídeos

Utilize o próprio ambiente de IA local do usuário para realizar a compactação de vídeos. Primeiro, verifique o ambiente, depois analise o material, pergunte sobre o objetivo, recomende parâmetros, forneça amostras; só execute em lote e oriente o arquivamento após receber a confirmação do usuário sobre as amostras específicas e o escopo do lote. Não descreva "validação automática aprovada" como se o usuário já tivesse aceitado a qualidade.

Os scripts complementares dependem apenas de Python 3.9+ da biblioteca padrão, FFmpeg e ffprobe. A primeira versão é voltada principalmente para macOS; a execução depende de bloqueios de arquivo POSIX. Ferramentas de chat comuns que não conseguem ler/escrever arquivos locais e executar comandos podem apenas fornecer orientação, não declarar que processaram o vídeo. Os scripts não precisam de chave de API de modelo, nem fazem upload do material.

Entrada e Diretório de Tarefas

  • Encontre o caminho absoluto desta Skill. No texto abaixo, <script> refere-se ao caminho absoluto de scripts/workflow.py; <tarefa> é um diretório de tarefas independente criado na máquina do usuário. Não escreva os resultados de volta no pacote da Skill instalado.
  • Crie um diretório de tarefas fora do diretório de material original do usuário; cada lote de tarefas mantém separadamente a lista, o plano, as amostras, a confirmação e o status. Para materiais novos ou alterados, crie outra tarefa; lotes já iniciados mantêm o plano original.
  • Instruções explícitas do usuário e autorizações já fornecidas têm precedência sobre as sugestões padrão desta Skill. Não pergunte repetidamente sobre metas, caminhos ou escolhas já definidas. Quando as solicitações do usuário excederem o suporte do script, explique as limitações e prepare uma solução separada, não altere o script de forma silenciosa nem degrade o processamento.

1. Verificação do Ambiente e Orientação de Instalação

Primeiro, confirme que o terminal pode encontrar o Python, depois execute python3 "<script>" doctor. Verifique a versão do Python, FFmpeg, ffprobe, libx265/libx264 e opções necessárias. Se houver falta, leia environment.md, explicando o que está faltando, como instalar e o impacto. Se o usuário já solicitou a instalação, execute dentro desse escopo; caso contrário, forneça comandos específicos primeiro para que o usuário escolha como executar. Não relate ferramentas ausentes como "nenhum vídeo". Após a instalação, verifique novamente até que esteja disponível para continuar.

2. Análise Somente Leitura do Material

Confirme o diretório de origem e o diretório de saída, execute init, scan. Os comandos estão em operations.md. A varredura lê apenas metadados de mídia, não inicia a codificação. Relate ao usuário a quantidade, volume, duração, resolução/taxa de quadros, profundidade de bits, marcadores de cor, faixas de áudio e os principais perfis, além de listar separadamente os arquivos que não podem ser lidos e os que precisam de revisão.

A etiqueta BT.709 não prova o modo de gravação nem descarta Log; combine com as informações de gravação fornecidas pelo usuário. O executor da primeira versão processa automaticamente apenas materiais H.264/HEVC com etiqueta BT.709 completa, 4:2:0, 8/10 bits; HLG/PQ/HDR, legendas, fluxos de vídeo principais múltiplos e cores desconhecidas são listados separadamente como REVIEW, sem conversão automática para SDR. Materiais conhecidos como Log são tratados separadamente primeiro, sem garantir ao usuário a precisão das cores.

3. Perguntar sobre o Objetivo de Uso

Primeiro, explique as descobertas da varredura; depois, faça apenas perguntas que ainda não estão claras e que podem alterar o plano: uso principal (visualização doméstica/preservação de longo prazo/edição contínua/compartilhamento), prioridade entre qualidade e tamanho, tempo de processamento aceitável, dispositivo de reprodução ou limite de tamanho de arquivo. Geralmente, combine em uma rodada curta de perguntas; não faça o usuário preencher uma tabela de parâmetros irrelevante.

Ao arquivar, explique duas opções: manter o original no local; ou mover para um subdiretório especificado no diretório pai original após sucesso e revalidação. O padrão é keep; mover requer escolha explícita do usuário; não forneça a função de deletar o original. Primeiro, determine essa escolha, depois gere a configuração da amostra.

4. Recomendar Esquemas Comparáveis

De acordo com quality.md, relacione o objetivo do usuário com o material real. Explique o encoder, preset, 2-3 opções de CRF candidatas, parâmetros preservados, trade-offs esperados e incertezas. Não torne CRF22, uma câmera específica ou um diretório uma regra fixa para todos os usuários.

Crie plan.json dentro da tarefa; o formato está em operations.md. Salve o objetivo do usuário e a justificativa da recomendação; selecione apenas os perfis com intenção de processamento clara nesta execução; cada perfil selecionado deve ter pelo menos uma amostra. Escolha segmentos representativos de movimento, textura, áreas escuras, etc.; quando os metadados não conseguirem identificar cenas, explique e peça ao usuário para especificar trechos importantes ou ajudar na visualização. Se houver muitos tipos de material, reduza o escopo em lotes.

Por padrão, mantenha resolução, taxa de quadros, proporção de aspecto, orientação, profundidade de bits, metadados de cor conhecidos e copie todas as faixas de áudio. O script copia apenas o fluxo de vídeo principal e as faixas de áudio; faixas de dados auxiliares/capas não entram na cópia compactada; explique isso no plano. Redimensionamento, ajuste de cor, conversão HDR, re-codificação de áudio, codificação por hardware, volume alvo estrito e formatos intermediários de edição não estão no escopo automático da primeira versão.

5. Amostras e Visualização Humana

Execute sample, exiba sample-report.md, o material de referência e os caminhos locais de cada candidato. Todos os candidatos são codificados a partir do mesmo segmento de referência. Explique a capacidade e o tempo de processamento, e oriente a comparação visual de detalhes, movimento, áreas escuras, gradientes, sincronização de áudio e vídeo, e no dispositivo de reprodução real; cortes em quadros-chave podem causar pequenos desvios de duração.

Não execute approve, run ou start até que o usuário aceite explicitamente um candidato. Se o usuário não estiver satisfeito, ajuste o plano, gere novas amostras e colete conclusões; não adivinhe "dentro dos requisitos". O PASS do script é uma verificação estrutural, não uma prova de qualidade quadro a quadro.

6. Execução em Lote Após Confirmação

Exiba o escopo de plan --crf N e o mapeamento de saída, o CRF selecionado, a estratégia de arquivamento e a base de amostra para tempo/capacidade estimados. Após o usuário confirmar que está disponível e concordar com a execução deste lote, use approve para registrar a resposta real do usuário; respostas que já cobriram esses itens não precisam ser perguntadas novamente. O registro de confirmação pode restaurar o contexto, mas não significa que o script possa provar que a resposta veio de um humano.

Após chamar start, use status e logs para confirmar a execução real. O lote processa sequencialmente com FFmpeg individual; a pausa segura só é possível após a conclusão da codificação, validação e arquivamento do arquivo atual. Use pause; não pause matando processos. resume limpa a solicitação de pausa; o controlador só inicia start após sair; não inicie novamente se um controlador já estiver em execução. Não mantenha a IA em polling de alta frequência para tarefas longas. Use as capacidades de notificação/agendamento do sistema de IA do usuário somente quando ele solicitar notificação posterior.

Mudanças nos parâmetros, caminhos, escopo ou amostras invalidam confirmações anteriores; tarefas já iniciadas são retomadas com o plano original; alterações criam nova tarefa. Relate separadamente itens com falha e pendentes de revisão. A retomada de ponto de interrupção é por arquivo; vídeos não concluídos são codificados desde o início.

7. Validação e Entrega de Arquivamento

De acordo com archival.md, explique a correspondência entre a versão compactada, o original e o registro da tarefa. Resuma os itens concluídos/pulados/pendentes de revisão, a diferença de capacidade das cópias compactadas, a localização atual dos originais e a forma de restauração. A taxa de compactação no relatório não equivale ao espaço real liberado: o original ainda é mantido; a ocupação de disco durante o fluxo atual geralmente aumenta.

Não sobrescreva originais ou saídas existentes; arquivos temporários não validados não são entregues como produto final. A validação automática é baseada em ffprobe, size/mtime, não em hash de conteúdo ou decodificação completa. Se o usuário precisar de validação ou backup mais rigorosos, projete as etapas correspondentes; mover diretórios não é backup. Mantenha o diretório da tarefa para que o usuário ou outro AI possa restaurar e interpretar os resultados.

Habilidades Relacionadas