transcript/README.md

Transcript

Um app desktop rápido para ditado local, transcrição e inserção automática de texto em qualquer lugar.

---

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:

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:

POST /v1/audio/transcriptions

Configuração local recomendada:

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:

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

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:

npm install

Rodar em modo desenvolvimento:

npm run tauri:dev

Validação:

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

Build frontend:

npm run build

---

Gerar instalador Windows

npm run tauri:build

Artefatos gerados:

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.