cjpais/Handy: Um aplicativo gratuito, de código aberto e extensível de conversão de fala em texto que funciona totalmente offline.

Um aplicativo de conversão de fala em texto gratuito, de código aberto e extensível que funciona totalmente offline.

Handy é um aplicativo de desktop multiplataforma desenvolvido com Tauri (Rust + React/TypeScript) que fornece transcrição de fala simples e com foco na privacidade. Pressione um atalho, fale e faça com que suas palavras apareçam em qualquer campo de texto, tudo sem enviar sua voz para a nuvem.

Handy foi criado para preencher a lacuna de uma ferramenta de conversão de fala para texto verdadeiramente aberta e extensível. Conforme declarado em hand.computer:

• Livre: As ferramentas de acessibilidade estão nas mãos de todos, não atrás de um acesso pago
• Código aberto: Juntos podemos construir mais. Estenda o Handy para você e contribua para algo maior
• Privado: sua voz permanece no computador. Obtenha transcrições sem enviar áudio para a nuvem
• Simples: Uma ferramenta, um trabalho. Transcreva o que você diz e coloque em uma caixa de texto

Handy não está tentando ser o melhor aplicativo de fala para texto – está tentando ser o mais fácil de usar.

1. Imprensa um atalho de teclado configurável para iniciar/parar a gravação (ou usar o modo push-to-talk)
2. Falar suas palavras enquanto o atalho está ativo
3. Liberar e Handy processa sua fala usando o Whisper
4. Pegar seu texto transcrito colado diretamente em qualquer aplicativo que você esteja usando

O processo é totalmente local:

• O silêncio é filtrado usando VAD (Voice Activity Detection) com Silero
• A transcrição usa sua escolha de modelos:
  • Modelos de sussurro (Pequeno/Médio/Turbo/Grande) com aceleração de GPU quando disponível
  • Periquito V3 – Modelo otimizado para CPU com excelente desempenho e detecção automática de idioma
• Funciona em Windows, macOS e Linux

1. Baixe a versão mais recente na página de lançamentos ou no site
2. Instale o aplicativo seguindo as instruções específicas da plataforma
3. Inicie o Handy e conceda as permissões de sistema necessárias (microfone, acessibilidade)
4. Configure seus atalhos de teclado preferidos em Configurações
5. Comece a transcrever!

Para obter instruções detalhadas de construção, incluindo requisitos específicos da plataforma, consulte BUILD.md.

Handy foi desenvolvido como um aplicativo Tauri que combina:

• Front-end: React + TypeScript com Tailwind CSS para a IU de configurações
• Back-end: Rust para integração de sistema, processamento de áudio e inferência de ML
• Bibliotecas principais:
  • whisper-rs: Reconhecimento de fala local com modelos Whisper
  • transcription-rs: Reconhecimento de fala otimizado para CPU com modelos Parakeet
  • cpal: E/S de áudio multiplataforma
  • vad-rs: Detecção de atividade de voz
  • rdev: Atalhos de teclado globais e eventos do sistema
  • rubato: Reamostragem de áudio

Handy inclui um modo de depuração avançado para desenvolvimento e solução de problemas. Acesse pressionando:

• macOS: Cmd+Shift+D
• Janelas/Linux: Ctrl+Shift+D

Este projeto está sendo desenvolvido ativamente e tem alguns problemas conhecidos. Acreditamos na transparência sobre o estado atual:

Falhas no modelo Whisper:

• Os modelos Whisper travam em determinadas configurações do sistema (Windows e Linux)
• Não afeta todos os sistemas – o problema depende da configuração
  • Se você tiver travamentos e for um desenvolvedor, ajude a corrigir e forneça logs de depuração!

Suporte Wayland (Linux):

• Suporte limitado para servidor de exibição Wayland
• Requer wtype ou dotool para que a entrada de texto funcione corretamente (veja as Notas do Linux abaixo para instalação)

Ferramentas de entrada de texto:

Para uma entrada de texto confiável no Linux, instale a ferramenta apropriada para o seu servidor de exibição:

• X11: Instalar xdotool para atalhos de digitação direta e colagem da área de transferência
• Wayland: Instalar wtype (preferencial) ou dotool para que a entrada de texto funcione corretamente
• configuração dotool: Requer adicionar seu usuário ao input grupo: sudo usermod -aG input $USER (depois saia e entre novamente)

Sem essas ferramentas, Handy recorre ao enigo, que pode ter compatibilidade limitada, especialmente no Wayland.

Outras notas:

• A sobreposição de gravação está desabilitada por padrão no Linux (Overlay Position: None) porque certos compositores a tratam como a janela ativa. Quando a sobreposição está visível, ela pode roubar o foco, o que impede que o Handy cole novamente no aplicativo que acionou a transcrição. Se você ativar a sobreposição de qualquer maneira, esteja ciente de que a colagem baseada na área de transferência pode falhar ou acabar na janela errada.

• Se você estiver tendo problemas com o aplicativo, execute com a variável de ambiente WEBKIT_DISABLE_DMABUF_RENDERER=1 pode ajudar

• Você pode gerenciar atalhos globais fora do Handy e ainda controlar o aplicativo por meio de sinais. Enviando SIGUSR2 ao processo Handy ativa/desativa a gravação, o que permite que os gerenciadores de janelas Wayland ou outros daemons de teclas de atalho mantenham a propriedade dos atalhos de teclado. Exemplo (balanço):

  bindsym $mod+o exec pkill -USR2 -n handy

  pkill aqui simplesmente entrega o sinal – não encerra o processo.

• macOS (Intel e Apple Silicon)
• Janelas x64
• Linux x64

A seguir estão recomendações para executar o Handy em sua própria máquina. Se você não atender aos requisitos do sistema, o desempenho do aplicativo poderá ser prejudicado. Estamos trabalhando para melhorar o desempenho em todos os tipos de computadores e hardware.

Para modelos Whisper:

• macOS: Mac série M, Intel Mac
• Windows: GPU Intel, AMD ou NVIDIA
• Linux: GPU Intel, AMD ou NVIDIA

Para o modelo Periquito V3:

• Operação somente CPU – funciona em uma ampla variedade de hardware
• Mínimo: Intel Skylake (6ª geração) ou processadores AMD equivalentes
• Desempenho: ~5x velocidade em tempo real em hardware de gama média (testado em i5)
• Detecção automática de idioma – não é necessária seleção manual de idioma

Estamos trabalhando ativamente em vários recursos e melhorias. Contribuições e feedback são bem-vindos!

Registro de depuração:

• Adicionar registro de depuração a um arquivo para ajudar a diagnosticar problemas

Melhorias no teclado do macOS:

• Suporte para chave Globe como gatilho de transcrição
• Uma reescrita do tratamento global de atalhos para MacOS e, potencialmente, para outros sistemas operacionais também.

Análise de aceitação:

• Colete dados de uso anônimos para ajudar a melhorar o Handy
• Abordagem que prioriza a privacidade com aceitação clara

Refatoração de configurações:

• Sistema de limpeza e refatoração de configurações que está ficando inchado e confuso
• Implemente melhores abstrações para gerenciamento de configurações

Limpeza de comandos Tauri:

• Abstrair e organizar padrões de comando Tauri
• Investigue o tauri-specta para melhorar a segurança e a organização do tipo

Se você estiver atrás de um proxy, firewall ou em um ambiente de rede restrito onde o Handy não pode baixar modelos automaticamente, você pode baixá-los e instalá-los manualmente. Os URLs são acessíveis publicamente a partir de qualquer navegador.

1. Abra as configurações úteis
2. Navegue até o Sobre seção
3. Copie o caminho “App Data Directory” mostrado lá ou use os atalhos:
   • macOS: Cmd+Shift+D para abrir o menu de depuração
   • Janelas/Linux: Ctrl+Shift+D para abrir o menu de depuração

Os caminhos típicos são:

• macOS: ~/Library/Application Support/com.pais.handy/
• Windows: C:\Users\{username}\AppData\Roaming\com.pais.handy\
• Linux: ~/.config/com.pais.handy/

Dentro do diretório de dados do seu aplicativo, crie um models pasta se ainda não existir:

# macOS/Linux
mkdir -p ~/Library/Application\ Support/com.pais.handy/models

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\com.pais.handy\models"

Baixe os modelos que você deseja abaixo

Modelos Whisper (arquivos .bin únicos):

• Pequeno (487 MB): https://blob.handy.computer/ggml-small.bin
• Médio (492 MB): https://blob.handy.computer/whisper-medium-q4_1.bin
• Turbo (1600MB): https://blob.handy.computer/ggml-large-v3-turbo.bin
• Grande (1100 MB): https://blob.handy.computer/ggml-large-v3-q5_0.bin

Modelos de Periquito (arquivos compactados):

• V2 (473MB): https://blob.handy.computer/parakeet-v2-int8.tar.gz
• V3 (478 MB): https://blob.handy.computer/parakeet-v3-int8.tar.gz

Para modelos Whisper (arquivos .bin):

Basta colocar o .bin arquivo diretamente no models diretório:

{app_data_dir}/models/
├── ggml-small.bin
├── whisper-medium-q4_1.bin
├── ggml-large-v3-turbo.bin
└── ggml-large-v3-q5_0.bin

Para modelos de periquito (arquivos .tar.gz):

1. Extraia o .tar.gz arquivo
2. Coloque o diretório extraído para dentro do models pasta
3. O diretório deve ser nomeado exatamente como segue:
   • Periquito V2: parakeet-tdt-0.6b-v2-int8
   • Periquito V3: parakeet-tdt-0.6b-v3-int8

A estrutura final deverá ficar assim:

{app_data_dir}/models/
├── parakeet-tdt-0.6b-v2-int8/     (directory with model files inside)
│   ├── (model files)
│   └── (config files)
└── parakeet-tdt-0.6b-v3-int8/     (directory with model files inside)
    ├── (model files)
    └── (config files)

Notas importantes:

• Para modelos Parakeet, o nome do diretório extraído deve corresponde exatamente como mostrado acima
• Não renomeie o .bin arquivos para modelos Whisper – use os nomes de arquivo exatos dos URLs de download
• Após colocar os arquivos, reinicie o Handy para detectar os novos modelos

1. Reinicie o prático
2. Abra Configurações → Modelos
3. Seus modelos instalados manualmente agora devem aparecer como “Baixados”
4. Selecione o modelo que deseja usar e teste a transcrição

1. Verifique os problemas existentes em github.com/cjpais/Handy/issues
2. Bifurque o repositório e crie uma ramificação de recursos
3. Teste completamente na sua plataforma alvo
4. Envie uma solicitação pull com descrição clara das mudanças
5. Participe da discussão – entre em contato pelo e-mail contact@handy.computer

O objetivo é criar uma ferramenta útil e uma base sobre a qual outros possam desenvolver: uma base de código simples e bem padronizada que atenda à comunidade.

Licença MIT – consulte o arquivo LICENSE para obter detalhes.

• Sussurrar pela OpenAI para o modelo de reconhecimento de fala
• sussurro.cpp e ggml para incrível inferência/aceleração de sussurros entre plataformas
• Silero para um excelente VAD leve
• Dificuldade equipe pela excelente estrutura de aplicativo baseada em Rust
• Contribuidores da comunidade ajudando a tornar o Handy melhor

“Sua busca pela ferramenta certa de conversão de fala em texto pode terminar aqui – não porque o Handy seja perfeito, mas porque você pode torná-lo perfeito para você.”