transcript/docs/superpowers/specs/2026-06-10-transcription-app-design.md

Design do Aplicativo de Transcrição Desktop

Objetivo

Construir um aplicativo desktop de transcrição para Windows e Linux, com foco inicial em operação offline. O usuário inicia e encerra gravações por hotkey global, revisa a transcrição em um modal flutuante editável e confirma a inserção no aplicativo de destino. O app deve permanecer residente na bandeja/barra do sistema e ser organizado para manutenção simples, builds automatizados e evolução incremental.

Requisitos aprovados

• Plataforma: Windows e Linux.
• Base técnica: Tauri + Rust com frontend web mínimo em TypeScript.
• Linux: suporte completo no X11 quando possível; suporte parcial e honesto no Wayland.
• Transcrição: offline-first.
• Modelo principal: cstr/parakeet-tdt-0.6b-v3-GGUF, arquivo parakeet-tdt-0.6b-v3-q8_0.gguf.
• Runtime local: CrispASR como sidecar.
• UX de revisão: sempre exibir modal editável antes de inserir texto.
• Inserção: padrão por clipboard + colar, com modo manual/fallback.
• App residente: tray/system tray com ações principais.
• CI/CD: preparado para GitHub Actions, com comandos portáveis para adaptação futura ao GitLab CI.

Arquitetura

O projeto usa uma arquitetura modular simples. O frontend Tauri renderiza o modal, configurações e estado visível. O backend Rust expõe comandos Tauri pequenos e delega cada responsabilidade a módulos focados.

src/                  Frontend TypeScript/CSS
src-tauri/src/
  audio/              Estado e gravação simulada/MVP
  transcription/      Contrato comum, CrispASR sidecar e API OpenAI-compatible
  injection/          Estratégias de inserção/cópia de texto
  models/             Catálogo, status e metadados de modelos offline
  settings/           Configuração local serializável
  tray.rs             Ícone da bandeja e menu
  ui_commands.rs      Comandos Tauri expostos ao frontend
  app_state.rs        Estado compartilhado mínimo
  lib.rs              Bootstrap Tauri
  main.rs             Entrada nativa

A implementação inicial entrega um esqueleto funcional e testável. Integrações que dependem de APIs nativas frágeis, como hotkey global e injeção real em Wayland, ficam isoladas por contratos para serem implementadas em fatias futuras sem reestruturar o app.

Modal flutuante

O modal é a interface principal após cada gravação. Ele sempre abre antes de qualquer inserção no aplicativo de destino.

Componentes:

• Cabeçalho com estado atual: pronto, gravando, transcrevendo ou revisando.
• Metadados: backend, modelo e idioma.
• Área editável para texto transcrito.
• Ações: iniciar/parar gravação, continuar, copiar, inserir, salvar.
• Mensagens de erro e fallback.

Fluxo principal:

Pronto -> Gravando -> Transcrevendo -> Revisando -> Inserido/Copiado/Salvo

Inserção de texto

A inserção padrão será ClipboardPaste: salvar clipboard atual, copiar transcrição, enviar colar quando o sistema suportar e restaurar clipboard depois de um atraso seguro. No MVP, a implementação real de colar é representada por contrato e fallback manual; o texto é copiado para o clipboard pelo frontend quando o usuário pressiona copiar.

Política por sistema:

• Windows: usar Win32 APIs em implementação futura (GetForegroundWindow, SetForegroundWindow, SendInput).
• Linux X11: usar X11 ou fallback com ferramenta opcional detectada.
• Linux Wayland: tratar como parcial; se automação for bloqueada, copiar texto e orientar Ctrl+V.

Modelos offline

O gerenciador de modelos começa com catálogo estático e validação por metadados.

Modelo principal:

• ID: parakeet-tdt-0.6b-v3-q8_0
• Repositório: cstr/parakeet-tdt-0.6b-v3-GGUF
• Arquivo: parakeet-tdt-0.6b-v3-q8_0.gguf
• Tamanho aproximado: 711 MiB / 745,121,600 bytes conforme metadados do repositório.
• Idiomas: modelo base Parakeet v3 com detecção automática e suporte a 25 idiomas europeus, incluindo português.

O app não embute o modelo no instalador principal. O instalador fica leve; o modelo é baixado pelo app ou instalado manualmente em diretório local configurado.

Transcrição local com CrispASR

CrispASR será executado como sidecar empacotado por Tauri. O contrato de transcrição aceita caminho de áudio e opções, e retorna texto, idioma detectado opcional, backend, modelo e duração.

No MVP, se o sidecar ou o modelo ainda não estiver configurado, o backend retorna mensagem clara de erro/pendência para o modal. Isso permite validar UI, settings e pipeline sem depender imediatamente do binário externo.

API OpenAI-compatible

A integração com API externa fica em adaptador separado. Campos previstos:

• endpoint base;
• API key;
• modelo;
• idioma opcional;
• timeout.

Esse adaptador não é o padrão inicial. Ele existe para manter a arquitetura pronta para fallback online sem contaminar o fluxo offline.

CI/CD

Workflows previstos:

• ci.yml: lint, typecheck, testes Rust, testes frontend e build web.
• build.yml: build desktop por matriz Windows/Linux.
• release.yml: publicação automática em GitHub Releases por tag v*.*.*.

A lógica principal fica em scripts npm/cargo para facilitar migração para GitLab CI.

Escopo do MVP implementado nesta primeira fatia

• Estrutura de projeto Tauri + Rust + TypeScript.
• Módulos backend com contratos e testes unitários.
• Catálogo do modelo Parakeet GGUF Q8.
• Configuração local padrão.
• Modal funcional no frontend com revisão, cópia e simulação de fluxo.
• Tray com menu básico.
• Workflows de CI/build/release.
• Documentação de desenvolvimento e arquitetura.

Fora do escopo imediato

• Captura real de áudio por dispositivo.
• Hotkey global real.
• Execução real do CrispASR em todos os SOs.
• Injeção real em aplicativos externos.
• Download real com barra de progresso.

Essas partes ficam isoladas em módulos para serem implementadas sem alterar a arquitetura principal.