georg-malahov/claude-skills

Skill de Vídeo

Processe e compartilhe vídeos usando ffmpeg, Deepgram Nova 3 e S3/túnel de compartilhamento.

Padrão: vídeo mais leve, mesma resolução

Sempre re-encode para um arquivo menor na resolução original da fonte por padrão. Uma cópia comprimida na mesma resolução é quase sempre o que o usuário deseja — uploads mais rápidos, compartilhamentos mais leves, experiência de visualização idêntica. Torne isso o padrão em todos os fluxos (silencioso, interativo e o encode de reprodução dev-video do Gemini); desvie apenas quando o usuário disser explicitamente o contrário. Concretamente:

• Otimização padrão = --resolution keep — re-encode com libx264 + CRF e sem filtro de scale, para que a resolução permaneça inalterada e o arquivo apenas fique menor. Esta é a escolha Q1 recomendada e o padrão do modo silencioso.
• Reduza a resolução (ex.: para 1080p) apenas quando a fonte for materialmente maior que 1080p (≥1440p / 4K) ou o usuário solicitar. Nunca aumente a resolução.
• Pule o re-encode (use o original intacto / stream-copy) apenas quando o usuário pedir explicitamente pelo original — ex.: "mantenha o original", "não re-encode".
• Verificação de segurança: após a codificação, compare o tamanho da saída com a fonte. Se não for significativamente menor (raro — ex.: uma fonte já com baixa taxa de bits), aumente o CRF (26–28) ou volte ao original. Gravações de tela comprimem especialmente bem: CRF 24–26 com preset slow rotineiramente corta 70–80% mantendo o texto na tela nítido.
• Botões de download: a página mostra um único botão "Download do Vídeo" por padrão (aponta para o vídeo de reprodução). Adicione um botão "Download do Original" — ou seja, passe render_page.py --original-filename <nome> — apenas quando você realmente enviar o original intacto para a pasta de saída com esse nome exato; caso contrário, o botão linkará para um arquivo ausente e resultará em 404. O fluxo padrão compress-manter não mantém um original separado, portanto não passe --original-filename.

Pré-requisitos

• ffmpeg e ffprobe devem estar instalados
• Python 3 deve estar disponível
• CLI aws deve estar disponível (para uploads S3)
• Chave da API Deepgram — para transcrição de áudio/legendas (mecanismo padrão)
• Chave da API OpenRouter — para o mecanismo de análise Gemini (modos dev-video / transcript-cheap). Opcional; necessária apenas quando esses modos forem selecionados.

Diretórios

• Scripts: <skill_dir>/scripts/ — todos os scripts Python e o template player.html
• Credenciais: ~/.config/video-skill/ — persistente entre atualizações do plugin
  • deepgram_token — chave da API Deepgram em uma única linha
  • openrouter_token — chave da API OpenRouter em uma única linha (mecanismo de análise Gemini)
  • s3_credentials — formato chave=valor (endpoint, bucket, access_key, secret_key)
• Preferências: ~/.config/video-skill/preferences.json — escolhas do usuário salvas entre sessões

Configuração de Credenciais

Se as credenciais estiverem ausentes quando necessárias, pergunte ao usuário via AskUserQuestion:

Deepgram: Verifique a env DEEPGRAM_API_KEY, depois o arquivo ~/.config/video-skill/deepgram_token. Se nenhum existir, pergunte ao usuário e salve no arquivo.

OpenRouter: Verifique a env OPENROUTER_TOKEN, depois o arquivo ~/.config/video-skill/openrouter_token. Necessário apenas para modos de análise dev-video / transcript-cheap. Se um modo Gemini for selecionado e o token estiver ausente, pergunte ao usuário e salve no arquivo.

S3: Verifique as env vars (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_ENDPOINT, S3_BUCKET), depois ~/.config/video-skill/s3_credentials. Se ausentes, pergunte ao usuário por endpoint, bucket, access_key, secret_key e salve.

Importante: Nunca passe credenciais como argumentos de CLI. Os scripts as leem de arquivos internamente via --credential-dir ~/.config/video-skill.

Preferências

{
  "language": "en",
  "last_folder": "/Users/example/screencasts",
  "share_folder": "/Users/example/screencasts",
  "sharing_method": "s3",
  "optimization": "compress-keep",
  "crf": 23,
  "preset": "medium",
  "audio": "aac-128k",
  "subtitles": "track",
  "subtitle_style": "modern",
  "subtitle_font": "Helvetica Neue",
  "target_language": "ru",
  "download_button": true,
  "passcode": true,
  "mode": "subtitles"
}

optimization: como o vídeo de reprodução é codificado. Padrão compress-keep = re-encode mais leve na resolução da fonte (--resolution keep). Outros valores: web-1080p (reduzir para 1080p — para fontes ≥1440p/4K), custom, keep-original (sem re-encode — apenas por solicitação explícita do usuário). Veja "Padrão: vídeo mais leve, mesma resolução" acima.

mode: um único campo que decide o mecanismo de transcrição/análise. Um de quatro valores (o antigo par analysis_mode + developer_analysis colapsado neste):

mode	Mecanismo	Legendas	Análise do desenvolvedor	Use quando
subtitles (padrão)	Deepgram	precisas	não	compartilhamento normal, só quer legendas
dev-audio	Deepgram	precisas	sim (a partir do texto da transcrição)	feedback de ferramenta/bug, quer legendas limpas também
dev-video	Gemini vídeo	aproximadas	sim + screenshots	feedback de UX/ferramenta mais rico (lê a tela)
transcript-cheap	Gemini áudio	aproximadas	não	transcrição aproximada barata, tempo não crítico

Internamente: subtitles/dev-audio executam process_and_share.py (o último com --developer-analysis); dev-video/transcript-cheap executam o mecanismo Gemini (gemini_analyze.py). "Análise do desenvolvedor" = o bloco de análise na página mais o artefato Markdown de Análise (veja aquela seção). Orientação do mecanismo (pesquisa 2026-06): mantenha Deepgram para legendas precisas; use Gemini-video para análise, Gemini-áudio para transcrições aproximadas baratas. Para dev-video onde legendas precisas também importam, execute adicionalmente uma passada Deepgram para a trilha.

Salvando: Após cada escolha interativa, atualize preferences.json. Sempre salve last_folder após cada execução. Carregando: Leia no início. Use valores salvos como padrões "(Recomendado)". No modo silencioso, use diretamente.

Referência de Scripts

Todos os scripts estão em <skill_dir>/scripts/. Eles aceitam --credential-dir para credenciais e imprimem linhas [PROGRESS] para rastreamento de status.

Script	Propósito	Argumentos Chave
process_and_share.py	Fluxo principal: otimizar + transcrever + renderizar + enviar	<video> --output-dir --share-folder --share s3|tunnel
share_existing.py	Compartilhar uma pasta pré-processada	<folder> --share-folder --share s3|tunnel
upload_s3.py	Enviar pasta para S3	<folder> --key <key> --credential-dir
render_page.py	Gerar index.html a partir do template	--output-dir --template --metadata
manage_registry.py	CRUD do registro (adicionar/remover/listar/obter/migrar)	<subcommand> --share-folder
partial_update.py	Re-renderizar + re-enviar uma pasta compartilhada (resolve chave do registro, encaminha senha)	<output_folder> [--key]
font_name.py	Imprimir o nome da família interna de um TTF (para ASS Fontname)	<font.ttf>
transcribe.py	Transcrição Deepgram → SRT + VTT	<video> --credential-dir [--language]
gemini_analyze.py	Mecanismo Gemini: transcrição de áudio OU análise de vídeo + screenshots	<video> --mode audio|video --output-dir --credential-dir [--key]
burn_subtitles.py	Queimar legendas no vídeo	<video> <srt> [--font --fontsize ...]
share_server.py	Servidor HTTP local para compartilhamento por túnel	<share_root> [--port]

Fluxo de Trabalho

Passo 0: Analisar Argumentos e Detectar Modo

Comandos:

• /video → Modo Interativo (Passos 1-5)
• /video process <caminho> → Modo Interativo para arquivo específico
• /video share → Modo Silencioso: processar o mais recente + compartilhar
• /video share <caminho> → Modo Silencioso: processar arquivo específico + compartilhar
• /video share <caminho> "contexto" → Modo Silencioso com contexto extra para metadados
• /video start → Iniciar servidor de compartilhamento + túnel
• /video stop → Parar compartilhamento
• /video status → Listar vídeos compartilhados
• /video copy <chave_ou_nome> → Copiar link + senha para a área de transferência
• /video remove <chave_ou_nome> → Remover do registro

---

Comandos de Compartilhamento (manipulados diretamente, sem processamento)

Registro de compartilhamento: <share_folder>/.share_registry.json — gerenciado por manage_registry.py.

Comando start:

1. Ler preferências → share_folder. Se não estiver definido, pergunte.
2. Verificar pgrep -f share_server.py. Se estiver em execução, mostrar status.
3. Iniciar servidor: python3 "<scripts>/share_server.py" "<share_folder>" --port 8080 &
4. Iniciar túnel: ssh -p 443 -R0:localhost:<port> -o StrictHostKeyChecking=no a.pinggy.io 2>&1 &
5. Analisar URL do túnel. Mostrar: "Servidor rodando em <base_url>"
6. Listar vídeos existentes com URLs completas (<base_url>/v/<chave>).

Comando stop: pkill -f share_server.py; pkill -f "ssh.*pinggy"; pkill -f "ngrok http"

Comando status:

1. Executar python3 "<scripts>/manage_registry.py" list --share-folder "<share_folder>"
2. Verificar pgrep -f share_server.py para status do túnel.
3. Exibir tabela: chave, título, URL S3, URL do túnel, senha, criado em.

Comando copy:

1. Executar python3 "<scripts>/manage_registry.py" get --share-folder "<share_folder>" --key "<consulta>"
2. Formatar: <título>\n<url>\nSenha: <código> → pbcopy

Comando remove: Executar python3 "<scripts>/manage_registry.py" remove --share-folder "<share_folder>" --key "<consulta>"

---

Modo Silencioso (/video share)

Uma confirmação, uma execução de script, interação mínima.

Fluxo:

1. Identificar vídeo (caminho do argumento ou o mais recente em last_folder / diretório atual)

2. Criar pasta de saída <share_folder>/<nome_do_video>/

3. Gerar senha (6 dígitos aleatórios ou preferência salva)

4. Mostrar confirmação:

   Compartilhamento rápido: demo.mov
   → mesma resolução · comprimido (CRF 23) · AAC 128k
   → Transcrever + legendas (trilha)
   → Compartilhar via S3 (link permanente)
   → Senha: 482910
   Prosseguir?
   

   Opções: Prosseguir (Recomendado) / Mudar para modo interativo

   Se mode for dev-video ou transcript-cheap, não execute process_and_share.py — siga a seção "Mecanismo de análise Gemini" em vez disso (silenciosamente, usando preferências salvas), e então ainda envie + registre o compartilhamento.

5. Executar o script do fluxo principal. Passe --developer-analysis quando mode for dev-audio:

   python3 "<scripts>/process_and_share.py" "<caminho_do_video>" \
       --output-dir "<pasta_de_saida>" \
       --share-folder "<pasta_de_compartilhamento>" \
       --credential-dir ~/.config/video-skill \
       --resolution keep --crf 23 --preset medium --audio aac-128k \
       --subtitles track \
       --share s3 \
       --passcode "<senha>" \
       [--developer-analysis] \
       [--context "<contexto_do_usuario>"]
   

   Padrão --resolution keep (comprimir, mesma resolução). Use --resolution 1080p apenas se a fonte for ≥1440p/4K, ou manipulação keep-original se o usuário quiser explicitamente o arquivo intacto.

6. Monitorar stdout por METADATA_READY: — quando o script imprimir este marcador: a. Leia o TRANSCRIPT_PREVIEW: e METADATA_INFO: que o precederam. b. Gere título, descrição e 4-8 capítulos a partir da prévia da transcrição. c. Se mode for dev-audio (análise do desenvolvedor ativa): construa o bloco de análise e o Markdown de Análise a partir da transcrição completa (leia o SRT/VTT no diretório de saída, não a prévia truncada). Veja as seções "Referência do metadata.json" e "Markdown de Análise" para a forma exata e contrato. Corresponda ao idioma da página (RU / DE / EN). d. Escreva metadata.json no diretório de saída conforme a referência do metadata.json. e. O script detecta metadata.json e continua automaticamente.

7. Script termina. Exibir resultado, l