transcript/README.md

<p align="center">
  <img src="assets/brand/logo.png" alt="Transcript logo" width="132" />
</p>

<h1 align="center">Transcript</h1>

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

<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>

---

## 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/
  app.ts              Interface TypeScript sem framework pesado
  styles.css          UI dark glass/acrylic + overlay de ditado

src-tauri/src/
  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
```

---

## Desenvolvimento local

Pré-requisitos:

- Node.js
- npm
- Rust stable
- Dependências do Tauri 2 para o seu sistema operacional

Instalação:

```bash
npm install
```

Rodar em modo desenvolvimento:

```bash
npm run tauri:dev
```

Validação:

```bash
npm run typecheck
npm run test -- --run
cargo test --manifest-path src-tauri/Cargo.toml
```

Build frontend:

```bash
npm run build
```

---

## Gerar instalador Windows

```bash
npm run tauri:build
```

Artefatos gerados:

```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
```

Use o instalador NSIS para uso diário enquanto novas versões são desenvolvidas.

---

## Estado atual

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.