# Mypheed

Culling e organização de fotos rápido: **lê o JPEG que a câmera já embutiu no RAW** em vez de renderizar o RAW, então voa entre milhares de imagens. App web local (Node + Express + ExifTool + Sharp) — abre no navegador, opera 100% por teclado.

Fase 1 (núcleo de culling) implementada e testada de ponta a ponta.

## Licença de uso

Trial completo de 14 dias; depois, ativação por chave assinada (Ed25519) — banner na barra de status → **Ativar licença**. Emissão: `node tools/gerar-licenca.mjs <email> [dias]` com a chave privada de `~\Mypheed-licencas\` (fora do repo; ver LEIA-ME de lá). O gate é do servidor: trial vencido → `/api/*` responde 403 (menos `/api/license` e `/api/progress`), e a UI mostra a tela de ativação. Estado em `%LOCALAPPDATA%\Mypheed\license.json`.

## Rodar

Requer **Node.js 24+** (o catálogo usa o SQLite embutido do Node).

```bash
npm install
npm start
```

Abre em `http://localhost:4555` (num terminal interativo o navegador abre sozinho). Clique em **Abrir pasta…**, navegue até a pasta de fotos e comece.

Porta alternativa: `PORT=4600 npm start`.

**Uso diário (Windows):** clique duplo em `Mypheed.bat` (sobe o servidor escondido e abre janela de app). `Instalar-Mypheed.bat` uma vez cria os atalhos (e instala as dependências se faltarem). Numa segunda máquina que **clonou** o repositório, `Atualizar-Mypheed.bat` puxa o código novo e realinha as dependências.

**macOS:** `bash Instalar-Mypheed.command` uma vez (confere o Node, instala dependências e cria o app *Mypheed* em `~/Applications`/Launchpad); depois abra pelo Launchpad ou pelo `Mypheed.command`. `Atualizar-Mypheed.command` equivale ao atualizador do Windows. Na primeira exclusão de fotos o sistema pede permissão para o Node controlar o Finder (é a Lixeira) — permita. Enviar para o Lightroom procura o app em `/Applications` (override: `MYPHEED_LIGHTROOM` apontando para o `.app`).

## Atalhos (a regra é: uma tecla por decisão)

| Tecla | Ação |
|---|---|
| ← → | anterior / próxima |
| ↑ ↓ | linha acima / abaixo |
| Home / End | primeira / última |
| **0–5** | estrelas |
| **R Y G B V** | cor: red / yellow / green / blue / violet |
| C | limpar cor |
| **P** | pick (selecionar) |
| **X** | reject (rejeitar) |
| U | tirar marca |
| **A** | auto-avanço: estrela/P/X pulam para a próxima foto (liga/desliga) |
| **Ctrl+Z / Ctrl+Y** | desfazer / refazer culling |
| Enter / F | tela cheia (loupe) |
| Z | zoom 100% na loupe (checar foco) |
| **H** | histograma + % de estouro (na loupe) |
| **N** | comparar selecionadas lado a lado (rajadas) |
| Ctrl+clique / Shift+clique / Ctrl+A | multi-seleção na grade |
| D | mover/copiar seleção para pasta… |
| Delete | enviar seleção para a Lixeira (com confirmação) |
| + / − | tamanho da miniatura |
| \\ | alternar filtro de marca (todas → picks → rejeitadas) |
| **M** | editor de metadados IPTC |
| ? | ajuda (as teclas de ação são remapeáveis em Ajuda → Personalizar atalhos) |

Filtros e ordenação ficam na barra superior (mín. estrelas, cor, marca, tipo, ordenar por nome/captura/estrelas/modificação).

## Importar do cartão (ingestão)

Botão **Importar cartão…**: copia cartão(ões) → destino (+ backup simultâneo opcional), renomeando na cópia se quiser — o cartão **nunca é alterado**, cada cópia é verificada por tamanho e re-rodar é idempotente. Aceita **2+ cartões numa passada** ("+ Adicionar cartão"): foto idêntica nos dois slots copia uma vez, par RAW+JPEG dividido entre slots é reunido, e nome repetido com conteúdo diferente (dois corpos) vira "nome (1)" — nunca sobrescreve nem descarta.

**Renomear em lote** (botão Renomear…) usa variáveis `{name} {seq} {yyyy} {mm} {dd} {hh} {min} {ss} {date} {time} {camera} {iso} {focal}` — as mesmas valem na renomeação da ingestão.

## Não-destrutivo (importante)

- O RAW **nunca é tocado**. Estrelas/cor/pick ficam num sidecar `.mypheed.json` na própria pasta — reabrir restaura tudo e volta ao mesmo cursor.
- **Reject não apaga.** "Mover rejeitadas → _rejected" move os arquivos para a subpasta `_rejected` (reversível: é só arrastar de volta).
- **Exportar** copia os selecionados para outra pasta (nunca move o original), e nunca sobrescreve arquivo existente.
- **Metadados:** RAW recebe **XMP sidecar** (`.xmp` ao lado, RAW intacto); JPEG/TIFF gravam IPTC/XMP embutidos. Estrelas/cor viram `XMP:Rating`/`XMP:Label`, então o Lightroom/Capture One leem tudo.

## Metadados IPTC (Fase 2) — tecla `M`

Editor em lote (foto atual / picks / filtradas / estrelas ≥ mínimo) com legenda, título, autor, copyright, cidade/estado/país, headline, instruções e palavras-chave.

- **Templates ("stamps"):** salve um conjunto de campos e reaplique com um clique (ex.: crédito + copyright padrão do estúdio).
- **Code Replacements:** dicionário código → texto. Digite `\ph` num campo e tecle **espaço** para expandir na linha completa de crédito. Ative/desative por job. Botão **Códigos…** dentro do editor.
- **Importar do arquivo:** lê o IPTC/XMP já existente (ex.: vindo do Lightroom) para o formulário.

## Como funciona por dentro

- **Preview embutido:** para JPEG, exibe o próprio arquivo; para RAW, o ExifTool extrai o maior JPEG embutido (`JpgFromRaw` → `PreviewImage` → `OtherImage` → `Thumbnail`). Sem preview embutido (e HEIC, que o Sharp pré-compilado não decodifica), entra um placeholder com nome/câmera/dimensões. Só o zoom 100% mexe em resolução alta.
- **Cache:** thumbnails ficam em `%LOCALAPPDATA%\Mypheed` (fora das suas pastas), invalidados por caminho+mtime+tamanho. Reabrir uma pasta já processada é instantâneo.
- **Cor:** o perfil ICC embutido (AdobeRGB/Display P3) é preservado no thumb para o navegador gerenciar a cor — sem "lavar" imagens wide-gamut.
- **RAW+JPEG:** mesmo basename vira um item só (badge `RAW+JPG`). Vídeos entram como item próprio com placeholder.
- **Virtualização:** a grade renderiza só o que está na viewport — milhares de fotos sem travar.
- **EXIF em background:** ao abrir, a leitura de metadados roda num pool com barra de progresso; a navegação não espera.

## Estrutura

```
src/server/   Express + scanner + thumbnails (ExifTool/Sharp) + sidecar + catálogo
src/web/      UI (HTML/CSS/JS puro, sem bundler): grade virtual, loupe, atalhos
```

## Entrega e IA (Fase 3)

**Export avançado** (no modal Exportar): além de copiar, reprocessa JPEG com **redimensionamento** (maior lado), **qualidade** ajustável e **marca d'água** de texto (posição + opacidade). RAW é sempre copiado intacto — nunca reprocessado. Para quem fotografa **só RAW**: a opção "RAW sem JPEG: gerar JPEG de entrega do preview embutido" produz o JPEG da entrega (com resize/qualidade/marca) a partir do preview que a câmera já embutiu — a prévia do mesmo dia sai daqui, sem passar pelo Lightroom.

**Galeria de prévia para o cliente** (checkbox no mesmo modal): a pasta exportada sai com um `index.html` **auto-contido** (grade responsiva + lightbox com setas/Esc, miniaturas em `_thumbs/`, título e crédito do estúdio) — manda o zip/pendrive/link da pasta e a prévia abre em qualquer navegador, **sem internet**. Re-exportar para a mesma pasta regenera a galeria com o que estiver lá.

**Pré-seleção local** (botão ✦ Pré-seleção): pontua cada foto por **foco** (nitidez) e **exposição** usando estatísticas de imagem — sem chamar API externa, sem custo. Sugere PICK (boa) ou REJECT (borrada/mal exposta) e aplica em lote após você confirmar. Você revisa e ajusta depois.

**Estrelas por IA** (botão ★ Estrelas IA…): sugere **0–3 estrelas** julgando momento, composição, luz e técnica — não só foco (foto sem foco perfeito pode ser 2–3★ se o momento sustenta). Como funciona:

- **Rubrica editável**: o julgamento segue um texto com âncoras por estrela (0 descartar / 1 entrega / 2 destaque / 3 portfólio) que você ajusta em "Editar rubrica…" (fica em `%LOCALAPPDATA%\Mypheed\rubrica-estrelas.md`; salvar vazio restaura o padrão).
- **Grupos de cena**: fotos com até 3s entre capturas são julgadas **juntas** (até 6 por chamada) — a IA compara as variações da rajada entre si, que é onde ranking relativo acerta mais que nota isolada.
- **Auditoria**: rode "Auditar contra meu culling" numa pasta que você **já cullou** — mostra a concordância (exata e ±1★) e as discordâncias clicáveis com a justificativa da IA. Ajuste a rubrica e audite de novo até calibrar; 4–5★ suas contam como 3 na comparação.
- **Aplicar é reversível**: as sugestões só gravam quando você clica Aplicar, e um **Ctrl+Z** desfaz o lote inteiro.
- Usa os previews em cache (768px) — nunca o RAW; custo aproximado no Haiku: ~US$ 1 por 1000 fotos. Requer `ANTHROPIC_API_KEY`.

**Legenda por IA** (botão ✦ Gerar com IA, no editor de metadados): manda a foto para a Anthropic e preenche **legenda + palavras-chave** em português. Requer credencial:

```bash
# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."; npm start
```

Modelo padrão: `claude-opus-4-8`. Para lotes grandes com menor custo, use Haiku:

```bash
$env:MYPHEED_AI_MODEL = "claude-haiku-4-5"
```

A legenda gerada **não** grava no arquivo sozinha — ela cai no formulário para você revisar e clicar **Aplicar** (curadoria humana no fim).

## Catálogo (Fase 3) — botão "Catálogo"

Índice persistente que busca em **toda a coleção**, independente da pasta aberta.

- **Adicionar pasta ao catálogo:** varre a árvore **recursivamente** (subpastas incluídas), lê EXIF, gera os thumbs em cache e grava um índice central em **SQLite** (`%LOCALAPPDATA%\Mypheed\catalog.db`, via `node:sqlite` — um `catalog.json` antigo migra sozinho no primeiro boot). Roda em background com barra de progresso.
- **Busca** por texto (nome, legenda, keyword, câmera, caminho) + filtros de estrelas, cor, marca e intervalo de datas de captura.
- **Funciona offline:** como os thumbs ficam em cache central, os resultados aparecem mesmo com o HD/NAS desconectado (marcados com selo `OFFLINE`).
- Clicar num resultado **abre a pasta** dele no culling principal.

O índice reflete o que o Mypheed sabe (culling + metadados do sidecar) — reindexar uma pasta atualiza os registros.

## Fases (do spec) — todas concluídas

- **Fase 1 — culling:** ✅ (ingestão/scan, grade virtualizada, teclado, filtros, export, rejeitar reversível).
- **Fase 2 — metadados:** ✅ (IPTC + templates + Code Replacements + XMP/embutido).
- **Fase 3 — diferenciais:** ✅ export com resize + marca d'água; pré-seleção local por foco/exposição; legenda/keywords por IA (Anthropic); catálogo persistente com busca na coleção.

Melhorias já incorporadas além do spec: `reject` reversível (nunca deleta), gestão de cor ICC, pareamento RAW+JPEG, suporte a vídeo, cache invalidado por mtime, retomar sessão pelo sidecar.
