# HermesKit

As capacidades de mídia do **Hermes Agent** empacotadas como **plugin MCP** para o
**Google Antigravity** (e para qualquer cliente MCP): editar vídeo, limpar e transcrever
áudio, gerar imagem, fazer OCR, operar o Chrome logado do usuário, ler/criar documentos e
gerar narração.

Tudo roda **na máquina**: ffmpeg, faster-whisper, ClearerVoice MossFormer2, ComfyUI/FLUX,
Tesseract, SAPI e Chrome via CDP. **Zero custo de API, zero upload de arquivo do usuário.**

## O que vem pronto

| Tool | O que faz |
|---|---|
| `kit_status` | diagnóstico do ambiente (ffmpeg, NVENC, Tesseract, ComfyUI, venvs, Chrome/CDP) |
| `media_probe` | duração, codecs, resolução, fps, bitrate, HDR, streams |
| `video_edit` | trim, scale, **vertical 1080x1920 sem tarja**, square, concat, extract_audio, replace_audio, mute, compress, speed, gif, burn_subs, rotate |
| `video_frames` | quadros em tempos exatos ou por fps + folha de contato em grade |
| `audio_denoise` | limpeza de ruído: `mossformer2` (melhor), `rnnoise`, `afftdn` |
| `audio_transcribe` | transcrição local com JSON/SRT/TXT (faster-whisper, CPU) |
| `audio_loudnorm` | normalização EBU R128 em duas passadas (−14 / −16 LUFS) |
| `image_generate` | geração de imagem local (ComfyUI + FLUX na GPU) |
| `image_ocr` | Tesseract em imagem ou PDF (com recorte e `psm`) |
| `image_process` | resize / pad / crop / square / thumbnail / convert |
| `tts` | narração offline pelas vozes SAPI do Windows (pt-BR Maria), WAV/MP3 |
| `browser` | Chrome **real** do usuário via CDP: abas, navegar, JS, clique, digitação, print, texto |
| `office` | ler/criar docx, xlsx e pptx; juntar PDF |

## Como está montado

```
C:\HermesKit\
├── mcp_server.py            # stdio JSON-RPC (MCP) — o único ponto de entrada
├── kittools.py              # registro: schemas + handlers
├── kitcore.py               # descoberta de ambiente, subprocesso, ffprobe, status
├── tools_media.py           # vídeo, áudio e imagem
├── tools_voice.py           # tts (SAPI)
├── tools_browser.py         # Chrome via CDP + Playwright
├── tools_office.py          # docx / xlsx / pptx / pdf
├── scripts/
│   ├── transcrever.py       # faster-whisper lendo WAV pela stdlib
│   ├── denoise_mossformer.py# ClearerVoice MossFormer2 (venv de voz)
│   └── tts.ps1              # SAPI -> WAV
├── antigravity/             # bundle do plugin (plugin.json, skill, regras, README)
├── setup-antigravity.ps1    # instala no Antigravity e testa o handshake
├── selftest.py              # 25 checagens de ponta a ponta via MCP
└── out/                     # saídas (fora do git)
```

O plugin do Antigravity é um **bundle**: `plugin.json` (identidade), `mcp_config.json`
(aponta para este `mcp_server.py`), `skills/hermes-kit/SKILL.md` (como usar) e
`rules/AGENTS.md` (convenções do usuário). Não há cópia do código: o plugin aponta para
o motor único neste diretório — corrigir aqui corrige nos dois lados.

## Requisitos

| Item | Para quê | Como |
|---|---|---|
| Windows 10/11 + Python 3.12+ | servidor MCP | `winget install Python.Python.3.14` |
| **ffmpeg/ffprobe** no PATH | todo o vídeo/áudio | `winget install Gyan.FFmpeg` |
| Pillow, requests | já vêm no Python do Hermes | `pip install pillow requests` |
| python-docx, openpyxl, pypdf, PyMuPDF, python-pptx | `office` | `pip install python-docx openpyxl pypdf pymupdf python-pptx` |
| Tesseract 5 (`por+eng`) | `image_ocr` | `winget install UB-Mannheim.TesseractOCR` |
| ComfyUI em `127.0.0.1:8188` | `image_generate` | instalação local do ComfyUI + checkpoint FLUX |
| `venv-whisper` com faster-whisper | `audio_transcribe` | ver abaixo |
| `C:\Users\<u>\voz-env` com `clearvoice` | `audio_denoise engine=mossformer2` | ver abaixo |
| Chrome com `--remote-debugging-port=9461` | `browser` | o `action=launch` sobe assim |
| Playwright (Python) | `browser` | `pip install playwright` (não precisa baixar browser) |

```powershell
# venv do whisper (Python 3.12: faster-whisper ainda não tem wheel para 3.14)
uv venv --python 3.12 "C:\HermesKit\venv-whisper"
uv pip install --python "C:\HermesKit\venv-whisper\Scripts\python.exe" faster-whisper numpy

# venv de voz (MossFormer2) — NUNCA no Python principal: clearvoice rebaixa o numpy
python -m venv C:\Users\<u>\voz-env
C:\Users\<u>\voz-env\Scripts\python.exe -m pip install clearvoice soundfile
```

Nada disso é obrigatório para subir o servidor: sem whisper o `audio_transcribe` responde
erro claro, sem ComfyUI o `image_generate` responde erro claro. `kit_status` diz o que existe.

## Instalação no Antigravity

```powershell
git clone https://github.com/renatopenner/hermes-kit C:\HermesKit
cd C:\HermesKit
powershell -NoProfile -ExecutionPolicy Bypass -File .\setup-antigravity.ps1
```

O script copia o bundle para `%USERPROFILE%\.gemini\config\plugins\hermes-kit`, gera o
`mcp_config.json` com os caminhos desta máquina, baixa os modelos rnnoise e testa o
handshake. Depois: **feche e reabra o Antigravity** (diretório de plugin novo só é
descoberto no startup) e habilite `hermes-kit` na página de Plugins.

## Verificação

```powershell
python selftest.py            # 25 checagens rápidas, arquivos reais
python selftest.py --image    # inclui image_generate (ComfyUI, ~45 s)
python selftest.py --full     # inclui MossFormer2
```

Cada linha imprime OK/FAIL, o tempo e o nome do arquivo produzido. Nada é simulado: se
aparece OK, o arquivo existe em `out\`.

## Exemplo: take bruto -> reels pronto

```
media_probe(input="take.mp4")
audio_transcribe(input="take.mp4", out_format="srt")
audio_denoise(input="take.mp4", engine="mossformer2")      # -> take_sem-ruido.mp4
video_edit(input="take_sem-ruido.mp4", action="trim", start=3.2, duration=38)
video_edit(input=<trim>.mp4, action="to_vertical")         # 1080x1920, crop, sem tarja
video_edit(input=<vert>.mp4, action="burn_subs", srt=<srt>)
audio_loudnorm(input=<final>.mp4, lufs=-14)
media_probe(input=<final_norm>.mp4)                        # prova a entrega
```

## Pitfalls que já custaram tempo

- **Caminho nativo** no ffmpeg (`C:/...`), nunca MSYS (`/c/...`).
- **`subtitles`** exige o `:` do drive escapado (`C\:/...`) — o kit já faz.
- **concat** precisa dos pads intercalados `[v0][a0][v1][a1]`.
- **NVENC** cai para libx264 sozinho quando o driver não suporta (`fallback` na resposta).
- **MossFormer2** devolve `(canais, amostras)` — sem transpor, dobra a duração.
- **faster-whisper 1.2.1 + PyAV 19** quebram em `metadata_errors`: o kit passa ndarray e
  nunca deixa o whisper abrir o arquivo.
- **CDP**: `browser.close()` fecha o Chrome do usuário; o kit só encerra a sessão do Playwright.
  Navegar sem `tab` abre aba nova, para não sequestrar a aba em uso.
- **Chrome do usuário**: nunca `taskkill chrome.exe` para "destravar" a porta.

## Licença

MIT — veja [LICENSE](LICENSE).