wip: snapshot das alterações não commitadas (2026-10-20)

Origem: D:/Documents/Github/transcript Arquivos omitidos (segredos, bancos de dados, logs, >50 MB): 2
2026-10-20 00:50:17 -03:00
1 parent 92c214254e
commit 06aaeeaf79
@@ -1,96 +1,230 @@
-# Transcript Desktop
+<p align="center">
+  <img src="assets/brand/logo.png" alt="Transcript logo" width="132" />
+</p>

-Aplicativo desktop de transcrição para Windows e Linux, construído com Tauri + Rust + TypeScript. O objetivo é oferecer ditado/transcrição offline-first com revisão obrigatória em modal antes de inserir texto em outro aplicativo.
+<h1 align="center">Transcript</h1>

-## Estado atual
+<p align="center">
+  Um app desktop rápido para ditado local, transcrição e inserção automática de texto em qualquer lugar.
+</p>

-Este repositório contém um MVP nativo funcional:
+<p align="center">
+  <img alt="Tauri" src="https://img.shields.io/badge/Tauri-2-111827?style=flat-square&logo=tauri" />
+  <img alt="Rust" src="https://img.shields.io/badge/Rust-backend-b7410e?style=flat-square&logo=rust" />
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-frontend-3178c6?style=flat-square&logo=typescript&logoColor=white" />
+  <img alt="OpenAI compatible" src="https://img.shields.io/badge/API-OpenAI--compatible-10a37f?style=flat-square" />
+  <img alt="Windows" src="https://img.shields.io/badge/Windows-supported-0078d4?style=flat-square&logo=windows" />
+</p>

- app Tauri 2 funcional;
- modal editável em TypeScript sem framework pesado;
- backend Rust modular;
- catálogo e download do modelo `cstr/parakeet-tdt-0.6b-v3-GGUF` em Q8;
- captura real de microfone em WAV via CPAL;
- execução do sidecar CrispASR/Parakeet;
- hotkey global `Ctrl+Shift+Space`;
- inserção híbrida por clipboard + paste automático no Windows/X11 quando disponível;
- fallback manual no Wayland;
- tray/system tray básico;
- CI, build e release via GitHub Actions.
+---
+
+## Por que este projeto existe?
+
+Digitar tudo manualmente é lento. A ideia do **Transcript** nasceu de uma frustração bem prática: muitos fluxos de trabalho exigem escrever o tempo todo — mensagens, prompts, documentos, tickets, código, respostas — mas os recursos nativos de ditado nem sempre entregam velocidade, precisão ou flexibilidade suficientes.
+
+A transcrição nativa do Windows, por exemplo, pode ser útil, mas ainda deixa a desejar quando você quer um fluxo realmente ágil: apertar um atalho global, falar naturalmente e ver o texto aparecer no campo em que você já estava digitando.
+
+O **Transcript** resolve esse problema com um fluxo direto:
+
+```text
+atalho global → fala → transcrição rápida → texto inserido no app em foco
+```
+
+Ele foi desenhado para quem quer escrever com a voz sem depender de interfaces pesadas, janelas grandes ou cópia manual constante.
+
+---
+
+## O que o Transcript faz
+
+O Transcript é um aplicativo desktop para Windows e Linux construído com **Tauri 2**, **Rust** e **TypeScript**. Ele grava sua voz, transcreve localmente com **whisper.cpp base multilingual** por padrão e insere o texto diretamente onde o cursor estava. APIs compatíveis com OpenAI continuam disponíveis como opção.
+
+### Principais recursos
+
+- **Hotkey global** — por padrão `Ctrl+Shift+Space`.
+- **Ditado em qualquer aplicativo** — navegador, editor, chat, terminal, IDE ou campo de texto.
+- **Overlay flutuante compacto** — uma barra inferior com waveform enquanto você fala.
+- **Transcrição local embutida** — inclui `whisper.cpp` + `ggml-base.bin` multilingual, com suporte a PT-BR sem Docker/API.
+- **API key opcional** — endpoints locais não precisam de chave; provedores externos podem usar chave salva com segurança.
+- **Credential Manager** — a chave nunca é salva em texto claro.
+- **Normalização com IA** — corrige erros comuns de transcrição sem mudar o significado.
+- **Engenharia de prompt** — normaliza a entrada e gera um prompt estruturado, adaptado ao domínio e à jurisdição explicitamente informada.
+- **Provedores de texto** — presets para OpenAI e Anthropic, além de endpoint customizado nos dois formatos.
+- **Inserção automática** — copia para o clipboard e tenta acionar `Ctrl+V` no app em foco.
+- **Fallback seguro** — se não conseguir inserir automaticamente, mantém o texto no clipboard.
+- **UI dark glass/acrylic** — interface compacta, frameless, sempre no topo e focada em velocidade.
+- **Health check antes de transcrever** — detecta API offline ou modelo inexistente antes de deixar o usuário esperando.
+
+---
+
+## Fluxo de uso
+
+1. Posicione o cursor em qualquer campo de texto.
+2. Pressione `Ctrl+Shift+Space`.
+3. Fale naturalmente.
+4. Pressione `Ctrl+Shift+Space` novamente.
+5. O Transcript transcreve e tenta inserir o texto automaticamente.
+
+Se a inserção automática não for possível, o texto fica no clipboard para você colar manualmente.
+
+---
+
+## Configuração recomendada
+
+Por padrão, o app funciona localmente com Whisper Base multilingual embutido. Para usar Docker, Parakeet/Speaches ou um provedor remoto, configure uma API compatível com OpenAI:
+
+```text
+POST /v1/audio/transcriptions
+```
+
+Configuração local recomendada:
+
+```text
+Endpoint: http://localhost:8022/v1/audio/transcriptions
+Modelo:   alefiury/parakeet-tdt-0.6b-v3-ptBR-TAGARELA-onnx
+Idioma:   pt
+api_key:  deixe em branco se o servidor local não exigir autenticação
+```
+
+Também funciona com provedores remotos compatíveis com OpenAI, incluindo o endpoint oficial:
+
+```text
+https://api.openai.com/v1/audio/transcriptions
+```
+
+### Assistente de texto
+
+Em **Configurações → Assistente de texto**, escolha OpenAI, Anthropic ou um endpoint customizado, informe o modelo e salve a chave. No editor, alterne entre **Normalizar** e **Criar prompt** e clique no botão de IA. O resultado substitui o texto do editor para poder ser revisado, copiado, salvo ou inserido.
+
+Endpoints customizados aceitam os formatos OpenAI Chat Completions e Anthropic Messages. A chave é opcional para endpoints customizados locais sem autenticação.
+
+---
+
+## Privacidade e segurança
+
+- Áudios são enviados apenas para o endpoint que você configurar.
+- Servidores locais permitem manter o fluxo dentro da sua máquina/rede.
+- `api_key` é armazenada no Credential Manager do sistema operacional.
+- O app não grava chaves em arquivos `.env`, JSON ou texto claro.
+- Textos só são enviados ao provedor quando o usuário aciona **Normalizar texto** ou **Criar prompt**.
+- Cada chave do assistente fica no Credential Manager e só é devolvida à interface após o usuário clicar em **Mostrar**.
+- A inserção de texto usa clipboard + paste automático; se falhar, o texto permanece no clipboard.
+
+---

 ## Arquitetura

 ```text
-src/                  Frontend TypeScript/CSS
+src/
+  app.ts              Interface TypeScript sem framework pesado
+  styles.css          UI dark glass/acrylic + overlay de ditado
+
 src-tauri/src/
-  audio/              Captura de microfone e gravação WAV
-  transcription/      Contratos, CrispASR sidecar e API compatível com OpenAI
-  injection/          Clipboard, paste automático e fallback manual
-  models/             Catálogo do modelo offline
-  settings/           Configuração padrão
-  tray.rs             Menu da bandeja do sistema
-  ui_commands.rs      Comandos Tauri expostos ao frontend
-  app_state.rs        Estado compartilhado mínimo
+  audio/              Captura de microfone e escrita WAV via CPAL + hound
+  transcription/      Cliente OpenAI-compatible multipart/form-data
+  text_processing.rs  Normalização e engenharia de prompt via OpenAI/Anthropic
+  injection/          Clipboard, Ctrl+V automático e fallback manual
+  secrets.rs          Integração com Credential Manager via keyring
+  shortcuts.rs        Hotkey global
+  ui_commands.rs      Comandos Tauri e fluxo nativo de ditado
+  app_state.rs        Estado compartilhado da aplicação
+  tray.rs             System tray
+
+assets/brand/
+  logo.png            Logo oficial do projeto
+  logo-*.png          Derivações em PNG
+
+src-tauri/icons/
+  icon.ico            Ícone oficial do app/instalador Windows
 ```

-A regra de design é manter arquivos pequenos, responsabilidades claras e zero overengineering. O app começa com contratos e stubs explícitos para as partes nativas mais arriscadas.
+---

-## Modelo offline principal
+## Desenvolvimento local

- Repositório: `cstr/parakeet-tdt-0.6b-v3-GGUF`
- Arquivo: `parakeet-tdt-0.6b-v3-q8_0.gguf`
- Quantização: `Q8_0`
- Tamanho registrado no catálogo: `745121600` bytes
- Modelo base: NVIDIA Parakeet TDT 0.6B v3
- Idioma: detecção automática; português incluído no conjunto suportado pelo modelo base.
+Pré-requisitos:

-O modelo não deve ser embutido no instalador principal. A estratégia recomendada é instalar o app leve e baixar o GGUF pelo gerenciador de modelos.
+- Node.js
+- npm
+- Rust stable
+- Dependências do Tauri 2 para o seu sistema operacional

-## Sidecar CrispASR
-
-O app chama por padrão o binário `parakeet-main` com:
-
-```bash
-parakeet-main -m <modelo.gguf> -f <audio.wav> -t <threads>
-```
-
-Para o modelo v3, o projeto CrispASR recomenda compilar o target `parakeet-main` no branch `parakeet`. O app limita automaticamente o número de threads a no máximo 4 para manter compatibilidade com PCs simples.
-
-Enquanto o binário não estiver no `PATH` ou empacotado como sidecar, a transcrição local retorna erro claro após a gravação.
-
-## Compatibilidade Windows/Linux
-
- Windows: clipboard + tentativa de `Ctrl+V` via `SendKeys`.
- Linux X11: clipboard + tentativa de `Ctrl+V` via `xdotool` quando instalado.
- Linux Wayland: suporte parcial por limitação de segurança dos compositors. O fallback seguro é copiar o texto e orientar o usuário a colar manualmente.
-
-## Comandos locais
+Instalação:

 ```bash
 npm install
+```
+
+Rodar em modo desenvolvimento:
+
+```bash
+npm run tauri:dev
+```
+
+Validação:
+
+```bash
 npm run typecheck
 npm run test -- --run
-npm run build
 cargo test --manifest-path src-tauri/Cargo.toml
+```
+
+Build frontend:
+
+```bash
+npm run build
+```
+
+---
+
+## Gerar instalador Windows
+
+```bash
 npm run tauri:build
 ```

-## CI/CD
+Artefatos gerados:

-Workflows:
+```text
+src-tauri/target/release/bundle/nsis/Transcript_0.1.0_x64-setup.exe
+src-tauri/target/release/bundle/msi/Transcript_0.1.0_x64_en-US.msi
+```

- `.github/workflows/ci.yml`: valida PRs e pushes em `main`.
- `.github/workflows/build.yml`: gera bundles Windows/Linux em push para `main` e manualmente.
- `.github/workflows/release.yml`: publica GitHub Releases em tags `v*.*.*`.
+Use o instalador NSIS para uso diário enquanto novas versões são desenvolvidas.

-A lógica fica em comandos npm/cargo para facilitar migração futura para GitLab CI.
+---

-## Fontes técnicas usadas
+## Estado atual

- Tauri 2 commands: https://v2.tauri.app/develop/calling-rust
- Tauri 2 system tray: https://v2.tauri.app/learn/system-tray
- Tauri 2 sidecars: https://v2.tauri.app/develop/sidecar
- Tauri GitHub pipelines: https://v2.tauri.app/distribute/pipelines/github
- Tauri Linux prerequisites: https://v2.tauri.app/start/prerequisites
- NVIDIA Parakeet v3 model card: https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3/blob/main/README.md
- cstr Parakeet GGUF: https://huggingface.co/cstr/parakeet-tdt-0.6b-v3-GGUF
+O projeto já possui:
+
+- gravação real de microfone;
+- transcrição local embutida com whisper.cpp base multilingual;
+- transcrição opcional via API compatível com OpenAI;
+- hotkey global;
+- overlay compacto de ditado;
+- health check de endpoint/modelo;
+- normalização e engenharia de prompt com OpenAI, Anthropic ou endpoint customizado;
+- inserção automática por clipboard + paste;
+- fallback manual;
+- app Windows sem terminal visível no build release;
+- ícone oficial no instalador e no app.
+
+---
+
+## Roadmap
+
+Ideias futuras:
+
+- rename completo para uma marca final, como **TypeVoz**;
+- seletor de modelos no app;
+- presets para provedores locais/remotos;
+- histórico de transcrições;
+- restauração segura do clipboard anterior;
+- waveform reativo ao volume real do microfone;
+- empacotamento e release automatizado.
+
+---
+
+## Licença
+
+Projeto em desenvolvimento. Defina a licença antes de publicar o repositório publicamente.