whisper-windows-mcp 2.2.0 → 2.2.2

package/ROADMAP.pt-BR.md

@@ -0,0 +1,286 @@
+# whisper-windows-mcp — Roadmap
+
+Versão atual: **v2.2.0**
+
+---
+
+## Princípios de design
+
+Estes princípios regem cada decisão neste projeto e têm prioridade sobre a velocidade de adição de funcionalidades.
+
+**Minimizar o uso da API do Claude.** Todo o fluxo de trabalho de transcrição — varredura, análise, fila, execução, validação, troca de modelos — deve ser executável com o menor número possível de interações com o Claude. Esta ferramenta deve funcionar completamente para usuários do Claude no plano gratuito que não pagam por assinaturas Pro ou Max. Cada chamada de ferramenta consome orçamento de uso. Projete de acordo.
+
+**Sempre uma única instância do whisper.** Nunca crie um segundo processo whisper-cli.exe enquanto um estiver em execução. O bloqueio de processo é obrigatório e inegociável.
+
+**Local em primeiro lugar, privado por padrão.** O áudio nunca sai da máquina. Nenhuma API de nuvem é necessária para a funcionalidade principal. Integrações opcionais (ex.: downloads de modelos do Hugging Face) devem ser claramente documentadas como opcionais.
+
+**Controle explícito do usuário.** Sem operações em massa silenciosas. Ações destrutivas ou irreversíveis exigem confirmação. O usuário deve sempre saber o que vai acontecer antes de acontecer.
+
+**Caminhos seguros para Unicode.** Toda E/S de arquivo deve lidar corretamente com nomes de arquivo não-ASCII, incluindo português, japonês, chinês, emoji, colchetes e outros caracteres especiais.
+
+**Modular e combinável.** As ferramentas são independentes. Os usuários usam o que precisam. Nenhuma funcionalidade deve exigir outra, a menos que seja inevitável.
+
+**Otimização antes de funcionalidades.** Quando em dúvida entre adicionar uma funcionalidade e reduzir a carga do sistema ou o número de chamadas de API, reduza a carga. Sessões de otimização grandes são caras. Projete a arquitetura corretamente desde o início.
+
+---
+
+## Concluído
+
+### ✅ v1.3.1 — Bloqueio de processo
+Adicionada verificação `isWhisperRunning()` usando `tasklist /FI` antes de criar qualquer processo de transcrição. Retorna um erro claro com instruções do Gerenciador de Tarefas em vez de criar um processo concorrente.
+
+### ✅ v1.4.0 — Aceleração GPU Vulkan
+Compilado whisper.cpp a partir do código-fonte com `-DGGML_VULKAN=ON` usando VS Build Tools 2022 e Vulkan SDK. Binários Vulkan pré-compilados distribuídos como `whisper-vulkan-win-x64.zip`.
+
+**Resultados no AMD Radeon RX Vega 56:** Utilização média de GPU ~16%. Arquivo de 58 minutos concluído em ~4,5 minutos na GPU vs. ~88 minutos apenas na CPU.
+
+### ✅ v1.5.0 — Diagnóstico do sistema
+Ferramenta `check_system`: detecção de GPU via `wmic`, verificação de DLL Vulkan, relatório de VRAM, recomendação de tamanho de modelo.
+
+### ✅ v1.6.0 — Pré-análise de arquivo
+Ferramenta `analyze_media` via FFprobe: duração, tamanho, codec, status de transcrição, estimativas de tempo de CPU e GPU. Varredura de arquivo único ou pasta com opções de ordenação.
+
+### ✅ v1.7.0 — Transcrição em segundo plano + Visibilidade do progresso
+Arquitetura de processo desanexado: `transcribe_audio` com `background=true` cria o whisper como um processo desanexado e retorna imediatamente um ID de tarefa. `check_progress` analisa os carimbos de tempo de segmento do stderr do whisper para porcentagem e ETA em tempo real.
+
+### ✅ v1.8.0 — Lote sequencial com validação
+`start_batch` e `check_batch_progress`: processamento sequencial automático, validação de transcrição (detecção de saída vazia/curta), avanço automático da fila, carimbos de tempo de progresso por arquivo.
+
+### ✅ v1.9.0 — Suporte multilíngue e tradução
+`generate_subtitles` com detecção `language=auto` e saída SRT dupla `translate_to_english=true`. Adicionado suporte para formatos `.3gp` e `.ts`. `language=auto` também disponível em `transcribe_audio`.
+
+**Limitação conhecida:** A tradução integrada do Whisper é direcionada apenas ao inglês. Requer modelo `large-v3` para idiomas que não sejam inglês — modelos somente inglês (`*.en.bin`) geram `[FOREIGN]` em áudio que não seja inglês.
+
+### ✅ v2.0.0 — Caminhos seguros para Unicode + SRT em segundo plano
+**Nomes de arquivo Unicode:** Arquivos com caracteres não-ASCII nos nomes causavam falha silenciosa na transcrição em segundo plano. Corrigido roteando toda a saída por um caminho temporário sanitizado baseado em ID de tarefa, depois movendo o resultado para o destino correto após a conclusão.
+
+**SRT no modo em segundo plano:** `spawnDetached` anteriormente codificava rigidamente `-otxt` independentemente do formato solicitado, e `generate_subtitles` bloqueava de forma síncrona e atingia o timeout MCP de 4 minutos em arquivos mais longos. Corrigido adicionando parâmetro `outputFormat` ao `spawnDetached`, suportando saída `text` e `srt` no modo em segundo plano.
+
+### ✅ v2.0.1 — Correções de bugs (incluído no v2.2.0)
+- `--max-context 0` fixo em `buildArgs` e `spawnDetached` — previne loops de alucinação em áudio longo. `--condition-on-previous-text` e `--no-context` não são flags válidos no binário atual (era v1.8.3) — `--max-context N` é o flag correto.
+- `--no-speech-thold 0.6` fixo em ambas as funções — segmentos abaixo do limiar de confiança são tratados como silêncio em vez de conteúdo alucinado.
+- Validação de caminho (`validateInputPath`) — rejeita caminhos UNC e travessias `..`.
+- Proteção de tamanho de arquivo `MAX_FILE_SIZE_MB = 10240`.
+- Comentário de segurança de injeção de transcrição em `transcribeSingle`.
+- Comando CLI de lote corrigido no TROUBLESHOOTING.md — documentado o método correto de pré-conversão do FFmpeg e o método `Start-Process -RedirectStandardOutput`.
+
+### ✅ v2.1.0 — Suite de gerenciamento de modelos (incluído no v2.2.0)
+- `WHISPER_MODEL` alterado de `const` para `let` (mutável dentro da sessão).
+- `MODEL_REGISTRY` — 16 modelos, variantes de precisão total e quantizadas, URLs de download do Hugging Face.
+- `ALLOWED_HF_PREFIXES` — lista de permissões de URL que limita downloads aos namespaces `ggerganov/whisper.cpp` e `ggml-org`.
+- Ferramenta `list_models` — varre o diretório de modelos, mostra o modelo ativo, tamanhos, casos de uso, downloads disponíveis.
+- Ferramenta `download_model` — baixa do Hugging Face via `https` integrado do Node.js, renomeação atômica (corrige condição de corrida de liberação de handle de arquivo do Windows).
+- Ferramenta `switch_model` — valida extensão `.bin`, restrição de diretório, verificação de bloqueio de processo.
+- `recommendedModel()` atualizado para recomendar `large-v3-turbo` para VRAM de 6GB+.
+
+### ✅ v2.2.0 — Expansão de qualidade, parâmetros e hardware (atual)
+- Interface `WhisperOptions` substituindo argumentos posicionais em `buildArgs`.
+- Novos parâmetros em `transcribe_audio`: `temperature`, `prompt`, `condition_on_prev_text`, `no_speech_thold`, `beam_size`, `best_of`, `gpu_device`, `processors`, `word_timestamps`, `max_segment_length`, `split_on_word`, `diarize`, `vad_model`, `offset_t`, `duration`.
+- Novos parâmetros em `generate_subtitles`: `temperature`, `prompt`, `beam_size`, `best_of`, `diarize`, `vad_model`.
+- `spawnDetached` refatorado — todos os flags de qualidade agora são aplicados no modo em segundo plano/lote.
+- `runSrtPass` atualizado para aceitar `extraOpts`.
+- Saída de lote corrigida — `readBatchProgress` agora move a saída temporária para o destino final antes de validar (esta era a causa raiz de todos os resultados de lote "com falha").
+
+**Nota de compatibilidade de flags:** `gpu_device` / `-g` foi adicionado no whisper.cpp v1.8.4. O binário Vulkan pré-compilado nos releases é da era v1.8.3 — este parâmetro é aceito pela ferramenta mas não terá efeito até que os usuários atualizem para binários v1.8.4+.
+
+**Flags válidos confirmados no binário atual (era v1.8.3):**
+`--max-context`, `--no-speech-thold`, `--processors`, `--offset-t`, `--duration`, `--best-of`, `--beam-size`, `--diarize`, `--tinydiarize`, `--temperature`, `--prompt`, flags VAD.
+
+**Ausentes no binário atual:** `--no-context` (use `--max-context 0`), `--condition-on-previous-text` (apenas nome da API Python), `--gpu-device` / `-g` (v1.8.4+).
+
+---
+
+## Bug crítico — Avanço automático do lote (confirmado, aguardando correção)
+
+### Lote não avança sem polling ativo
+
+`start_batch` não avança a fila autonomamente entre os arquivos. O lote só avança quando `check_batch_progress` é chamado. Sem polling, o lote fica parado indefinidamente após cada arquivo — o whisper-cli.exe sai, nenhum novo processo é criado e a fila não avança.
+
+Isso destrói o objetivo de design central de processamento em lote autônomo durante a noite e viola diretamente o princípio de design de minimizar chamadas à API do Claude. Um lote de 95 clipes curtos exigiu cerca de 200 chamadas de polling ao longo de 100 minutos para ser concluído.
+
+**Causa raiz:** `readBatchProgress` contém toda a lógica de avanço de fila. Ele só é executado quando `check_batch_progress` é chamado explicitamente. Não há timer em segundo plano, observador de arquivo ou loop autônomo.
+
+**Correção planejada — Opção B (callback de saída, fortemente preferido):** Attach de um handler `on('exit')` ao processo filho whisper-cli criado. Quando o processo sair, imediatamente chamar a lógica de avanço para validar a saída e criar a próxima tarefa. Baseado em eventos, disparado exatamente uma vez por conclusão de arquivo, sem overhead de polling, sem chamadas de API consumidas.
+
+**Opção A (somente fallback):** `setInterval` em segundo plano com intervalo de polling baseado em duração derivado dos dados de duração do FFprobe já presentes no JSON de estado do lote. O tamanho do arquivo não é um substituto confiável para a duração.
+
+**Restrição adicional:** A correção não deve criar um segundo whisper-cli.exe quando um já está em execução — o bloqueio de processo deve ser respeitado no caminho de avanço automático.
+
+**Solução alternativa (atual):** Chame `check_batch_progress` repetidamente até que o lote seja concluído. Cerca de um polling por arquivo é necessário.
+
+---
+
+## Planejado — Arquitetura de Privacidade (antes da migração para o Bun)
+
+Essas mudanças devem ser lançadas antes da migração para o Bun e antes de quaisquer mudanças de licença que facilitem a adoção comercial ou empresarial. Lançar uma ferramenta de nível empresarial sem proteções de conformidade resolvidas cria responsabilidade para usuários em setores regulamentados.
+
+### Variável de ambiente `WHISPER_PRIVACY_MODE`
+A ferramenta atualmente garante que nenhum **áudio** sai da máquina. Ela não estende essa garantia ao **texto de transcrição** — quando o conteúdo de transcrição é retornado inline em uma resposta de ferramenta, esse texto é processado pela API do Claude e sai do ambiente local.
+
+Essa lacuna é invisível para usuários que razoavelmente interpretam "nenhum dado sai da sua máquina" como cobrindo todo o conteúdo derivado do seu áudio.
+
+Adicionar `WHISPER_PRIVACY_MODE` como variável de ambiente em `claude_desktop_config.json`. Quando ativado:
+- Todas as respostas das ferramentas retornam apenas metadados: nome do arquivo, duração, contagem de palavras, status de conclusão
+- Nenhum texto de transcrição é incluído em qualquer resposta de ferramenta
+- O Claude não pode ler, analisar ou retransmitir conteúdo de transcrição de nenhuma forma
+- As transcrições existem apenas como arquivos `.txt` locais
+
+Esta é a configuração correta para implantações médicas, jurídicas, financeiras e corporativas. Zero chamadas de API, zero transmissão de dados, zero risco de conformidade.
+
+### Gateway de consentimento para conteúdo de transcrição
+Quando `WHISPER_PRIVACY_MODE` não está ativado (padrão), qualquer resposta de ferramenta que inclua texto de transcrição deve ser precedida de uma divulgação no primeiro uso por sessão. A divulgação deve comunicar claramente que o texto de transcrição é enviado à API da Anthropic, que isso está fora da garantia "nenhum dado sai da sua máquina", e que usuários que lidam com conteúdo regulamentado devem verificar suas obrigações de conformidade antes de prosseguir.
+
+Implementação: variável de ambiente `WHISPER_CONSENT_ACKNOWLEDGED` com padrão `false`. No primeiro retorno de transcrição por sessão, se não reconhecido, o Claude apresenta a divulgação e solicita confirmação explícita. Uma vez reconhecido para a sessão, as transcrições subsequentes são retornadas sem solicitar novamente.
+
+### Documentação `PRIVACY.md`
+Criar `PRIVACY.md` na raiz do repositório cobrindo:
+- Quais dados sempre ficam locais: arquivos de áudio, vídeo, modelos
+- Quais dados podem sair do local (por padrão): texto de transcrição em respostas de ferramentas
+- Quais dados nunca saem do local (com modo de privacidade): tudo
+- Orientação de framework de conformidade por setor (HIPAA, GDPR, privilégio advogado-cliente, FERPA, SOX, PCI-DSS, NDA/segredo comercial)
+- Como configurar o modo de privacidade
+- Isenção de responsabilidade de que os autores da ferramenta não são consultores jurídicos
+
+### Avisos de privacidade no esquema de ferramentas
+Atualizar as descrições de ferramentas `ListToolsRequestSchema` para incluir uma nota de privacidade em qualquer ferramenta que retorne texto de transcrição. Isso aparece nas descrições de ferramentas do Claude Desktop e cria consciência no ponto de uso.
+
+### Limpeza automática do diretório temporário
+`%TEMP%\whisper-mcp-jobs\` acumula arquivos de estado de tarefas e logs ao longo do tempo. Adicionar limpeza automática de arquivos de tarefas concluídas após uma janela de retenção configurável (padrão: 7 dias). Atualmente requer `Remove-Item` manual pelo usuário.
+
+---
+
+## Planejado — Migração para o Bun
+
+Migrar o runtime do Node.js para o [Bun](https://bun.sh) após a conclusão da arquitetura de privacidade e antes das adições de funcionalidades do v2.3.0.
+
+Como o Claude Desktop cria um novo servidor MCP a cada início de sessão, o tempo de inicialização está no caminho crítico. O Bun executa TypeScript nativamente sem etapa de compilação, inicia significativamente mais rápido que o Node e tem E/S mais rápida.
+
+**O que muda:**
+- Eliminação da etapa de build `tsc` e do diretório `dist/`
+- Os usuários executam o código TypeScript fonte diretamente
+- `tsconfig.json` torna-se opcional
+- Scripts `package.json` atualizados
+- Fluxo de trabalho de publicação no npm atualizado
+
+**O que não muda:**
+- Código-fonte `src/index.ts` — o Bun é compatível com o TypeScript existente e as APIs integradas do Node.js
+- Todos os comportamentos de ferramentas e formatos de saída
+- Configuração do Claude Desktop para usuários finais
+
+**Por que após a privacidade, antes do v2.3.0:** O código-fonte está em seu estado mais fácil de migrar agora. Migrar após adicionar mais ferramentas apenas aumenta a área de superfície sem benefício. A arquitetura de privacidade deve ser lançada primeiro conforme observado acima.
+
+---
+
+## Licenciamento
+
+whisper-windows-mcp usa licença dupla.
+
+**Uso não comercial:** MIT — gratuito para uso pessoal, educacional e não comercial. Veja [LICENSE](LICENSE).
+
+**Uso comercial:** É necessário um contrato de licença comercial separado. Veja [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md).
+
+`WHISPER_PRIVACY_MODE` para implantações em setores regulamentados está em desenvolvimento e planejado para uma versão futura. Veja [PRIVACY.md](PRIVACY.md) para orientações atuais.
+
+## Planejado — v2.3.0: Expansão de formatos de saída
+
+### Formato de legenda VTT
+Saída WebVTT (`.vtt`) junto com SRT. VTT é o padrão web usado pelo YouTube, HTML5 `<video>` e a maioria dos players modernos. O whisper-cli o suporta nativamente. Adicionar `vtt` como formato de saída válido em `transcribe_audio`, `generate_subtitles` e `spawnDetached`. Atualizar `buildArgs` e todos os esquemas de ferramentas relevantes, README e documentação multilíngue.
+
+### Formato LRC
+Saída no formato LRC (`.lrc`) de letras/karaokê via `-olrc`. Usado por players de mídia para exibição sincronizada de letras. Custo de implementação zero — flag CLI nativo.
+
+### Formato CSV
+Saída CSV (`.csv`) via `-ocsv`. Dados tabulares estruturados com timing de segmentos — útil para análise downstream, fluxos de trabalho de alinhamento de clipes e importação em ferramentas de planilha. Custo de implementação zero — flag CLI nativo.
+
+---
+
+## Planejado — Releases futuros
+
+### TinyDiarize
+Suporte ao flag `--tinydiarize` com variantes de modelo que suportam `tdrz` (ex.: `large-v2-tdrz`). Ao contrário do flag `--diarize` estéreo, o TinyDiarize funciona em gravações mono. Requer download de variante de modelo especial. Precisão menor que a diarização baseada em pyannote, mas sem dependências adicionais além do arquivo de modelo.
+
+**Status:** Planejado. Depende do `download_model` suportar variantes de modelo tdrz.
+
+### Transcrição de URL do YouTube
+Transcrição direta de URLs do YouTube via yt-dlp. Baixa áudio e transcreve em uma única etapa. Requer yt-dlp instalado e no PATH.
+
+**Restrições de design:** yt-dlp é opcional. A ferramenta deve degradar graciosamente com instruções claras de instalação se não encontrado. Sem mudanças na funcionalidade principal para usuários que não precisam disso.
+
+### Ferramentas de fluxo de trabalho de projeto de vídeo
+Para usuários que gerenciam grandes projetos de edição de vídeo com diretórios de clipes fonte e editados:
+
+1. Varrer diretório fonte e subdiretórios de clipes
+2. Fazer correspondência fuzzy de transcrições de clipes editados com transcrições fonte para encontrar pontos de origem
+3. Exibir nomes de arquivo descritivos sugeridos pelo Claude com base no conteúdo de transcrição, exigindo confirmação explícita do usuário antes de executar qualquer renomeação
+4. Pesquisa de transcrição em todo o diretório do projeto com resultados de timecode
+
+**Restrições de design:**
+- Arquivos fonte **nunca são renomeados ou modificados**
+- Todas as renomeações exigem **confirmação explícita do usuário**
+- A pesquisa é uma ferramenta autônoma utilizável de forma independente
+- A análise e correspondência acontecem localmente — o Claude é chamado apenas quando o usuário revisa os resultados, minimizando chamadas de API
+
+**Status:** Fase de design.
+
+### Diarização de falantes (pyannote-audio)
+Diarização de falantes mono completa com rótulos de ID de falante — marca transições de falantes em toda a gravação independentemente da configuração de canal. Diferente do flag `--diarize` estéreo integrado (v2.2.0) e do TinyDiarize.
+
+**Implementação:** Requer [pyannote-audio](https://github.com/pyannote/pyannote-audio) — biblioteca baseada em Python com requisito de token de acesso a modelos do Hugging Face. Pilha de dependências completamente separada do pipeline whisper.cpp.
+
+**Status:** Funcionalidade avançada opcional com sua própria documentação de configuração. Não incluída no pacote principal.
+
+### Tradução para idiomas que não sejam inglês
+O flag `--translate` do Whisper é direcionado apenas ao inglês. Suportar idiomas de destino arbitrários requer uma API de tradução externa ou modelo de tradução local.
+
+**Opções em consideração:** LibreTranslate (pode ser auto-hospedado, local em primeiro lugar), tradução via LLM local ou documentação explícita de fora do escopo.
+
+**Status:** Adiado aguardando decisão de design sobre local em primeiro lugar vs. dependência de API.
+
+### Limpeza e formatação de transcrições
+Pipeline de pós-processamento:
+- Remoção de palavras de preenchimento e falsos começos (opcional, controlado pelo usuário)
+- Quebras de parágrafo em limites de tópicos naturais
+- Formatação com consciência de falante combinada com saída de diarização
+- Exportação para PDF ou DOCX
+
+**Status:** Planejado. A variante com consciência de falante depende da diarização.
+
+---
+
+## Distribuição
+
+Disponível no [npm](https://www.npmjs.com/package/whisper-windows-mcp), [mcpservers.org](https://mcpservers.org) e [Glama](https://glama.ai).
+
+---
+
+## Documentação multilíngue
+
+A documentação em japonês, coreano, vietnamita, indonésio, ucraniano, português brasileiro e espanhol é mantida em paralelo com o inglês. Os seguintes arquivos devem ser atualizados para corresponder aos documentos em inglês após cada release:
+
+**Japonês (`*.ja.md`)** — `README.ja.md` / `TROUBLESHOOTING.ja.md` / `ROADMAP.ja.md` / `PRIVACY.ja.md` / `SECURITY.ja.md`
+
+**Coreano (`*.ko.md`)** — `README.ko.md` / `TROUBLESHOOTING.ko.md` / `ROADMAP.ko.md` / `PRIVACY.ko.md` / `SECURITY.ko.md`
+
+**Vietnamita (`*.vi.md`)** — `README.vi.md` / `TROUBLESHOOTING.vi.md` / `ROADMAP.vi.md` / `PRIVACY.vi.md` / `SECURITY.vi.md`
+
+**Indonésio (`*.id.md`)** — `README.id.md` / `TROUBLESHOOTING.id.md` / `ROADMAP.id.md` / `PRIVACY.id.md` / `SECURITY.id.md`
+
+**Ucraniano (`*.uk.md`)** — `README.uk.md` / `TROUBLESHOOTING.uk.md` / `ROADMAP.uk.md` / `PRIVACY.uk.md` / `SECURITY.uk.md`
+
+**Português Brasileiro (`*.pt-BR.md`)** — `README.pt-BR.md` / `TROUBLESHOOTING.pt-BR.md` / `ROADMAP.pt-BR.md` / `PRIVACY.pt-BR.md` / `SECURITY.pt-BR.md`
+
+**Espanhol (`*.es.md`)** — `README.es.md` / `TROUBLESHOOTING.es.md` / `ROADMAP.es.md` / `PRIVACY.es.md` / `SECURITY.es.md`
+
+**Polish (`*.pl.md`)** — `README.pl.md` / `TROUBLESHOOTING.pl.md` / `ROADMAP.pl.md` / `PRIVACY.pl.md` / `SECURITY.pl.md`
+
+**Romanian (`*.ro.md`)** — `README.ro.md` / `TROUBLESHOOTING.ro.md` / `ROADMAP.ro.md` / `PRIVACY.ro.md` / `SECURITY.ro.md`
+
+Contribuições da comunidade para outros idiomas são bem-vindas.
+
+---
+
+## Contribuições
+
+Pull requests são bem-vindos. Verifique as issues existentes antes de começar a trabalhar.
+
+Se você testou a aceleração por GPU em hardware não listado acima, abra uma issue com o modelo da GPU, VRAM, tamanho do modelo e throughput observado. Isso ajuda a construir uma referência de desempenho precisa para outros usuários.

package/ROADMAP.ro.md

@@ -0,0 +1,200 @@
+# whisper-windows-mcp — Foaie de parcurs
+
+Versiunea curentă: **v2.2.0**
+
+---
+
+## Principii de proiectare
+
+Aceste principii guvernează fiecare decizie din acest proiect și au prioritate față de viteza de adăugare a funcțiilor.
+
+**Minimizarea utilizării API-ului Claude.** Întregul flux de lucru de transcriere — scanare, analiză, coadă, execuție, validare, schimbare modele — trebuie să poată fi executat cu cât mai puține interacțiuni Claude posibil. Acest instrument trebuie să funcționeze complet pentru utilizatorii Claude cu plan gratuit care nu plătesc pentru abonamente Pro sau Max. Fiecare apel de instrument consumă buget de utilizare. Proiectează în consecință.
+
+**Întotdeauna o singură instanță whisper.** Nu crea niciodată un al doilea proces whisper-cli.exe când unul rulează deja. Blocarea proceselor este obligatorie și nu poate fi negociată.
+
+**Local prioritar, privat implicit.** Audio-ul nu părăsește niciodată calculatorul. Niciun API cloud nu este necesar pentru funcționalitatea de bază. Integrările opționale (ex.: descărcări de modele de la Hugging Face) trebuie documentate clar ca opționale.
+
+**Control explicit al utilizatorului.** Fără operațiuni în masă silențioase. Acțiunile distructive sau ireversibile necesită confirmare. Utilizatorul trebuie să știe întotdeauna ce se va întâmpla înainte să se întâmple.
+
+**Căi sigure pentru Unicode.** Toată I/O de fișiere trebuie să gestioneze corect numele de fișiere non-ASCII, inclusiv română, japoneză, chineză, emoji, paranteze și alte caractere speciale.
+
+**Modular și combinabil.** Instrumentele sunt independente. Utilizatorii folosesc ce au nevoie. Nicio funcție nu ar trebui să necesite alta, cu excepția cazurilor inevitabile.
+
+**Optimizare înainte de funcții.** Când ai îndoieli între adăugarea unei funcții și reducerea sarcinii sistemului sau a numărului de apeluri API — reduce sarcina. Sesiunile mari de optimizare sunt costisitoare. Proiectează arhitectura corect de la început.
+
+---
+
+## Finalizat
+
+### ✅ v1.3.1 — Blocare procese
+Adăugat verificarea `isWhisperRunning()` folosind `tasklist /FI` înainte de a crea orice proces de transcriere. Returnează o eroare clară cu instrucțiuni Task Manager în loc să creeze un proces concurent.
+
+### ✅ v1.4.0 — Accelerare GPU Vulkan
+Compilat whisper.cpp din sursă cu `-DGGML_VULKAN=ON` folosind VS Build Tools 2022 și Vulkan SDK. Binarele Vulkan precompilate distribuite ca `whisper-vulkan-win-x64.zip`.
+
+**Rezultate pe AMD Radeon RX Vega 56:** Utilizare medie GPU ~16%. Fișier de 58 minute finalizat în ~4,5 minute pe GPU față de ~88 minute numai CPU.
+
+### ✅ v1.5.0 — Diagnosticare sistem
+Instrument `check_system`: detectare GPU prin `wmic`, verificare DLL Vulkan, raportare VRAM, recomandare dimensiune model.
+
+### ✅ v1.6.0 — Pre-analiză fișier
+Instrument `analyze_media` prin FFprobe: durată, dimensiune, codec, stare transcriere, estimări timp CPU și GPU. Scanare fișier unic sau folder cu opțiuni de sortare.
+
+### ✅ v1.7.0 — Transcriere în fundal + Vizibilitate progres
+Arhitectură proces detașat: `transcribe_audio` cu `background=true` pornește whisper ca proces detașat și returnează imediat ID-ul sarcinii. `check_progress` parsează marcajele de timp ale segmentelor stderr whisper pentru procent și ETA în timp real.
+
+### ✅ v1.8.0 — Lot secvențial cu validare
+`start_batch` și `check_batch_progress`: procesare secvențială automată, validare transcriere (detectare ieșire goală/scurtă), avansare automată coadă, marcaje de timp progres per fișier.
+
+### ✅ v1.9.0 — Suport multilingv și traducere
+`generate_subtitles` cu detecție `language=auto` și ieșire SRT dublă `translate_to_english=true`. Adăugat suport formate `.3gp` și `.ts`. `language=auto` disponibil și în `transcribe_audio`.
+
+**Limitare cunoscută:** Traducerea încorporată Whisper țintește doar engleza. Necesită model `large-v3` pentru limbi non-engleze — modelele numai engleză (`*.en.bin`) generează `[FOREIGN]` pentru audio non-englezesc.
+
+### ✅ v2.0.0 — Căi sigure Unicode + SRT în fundal
+**Nume fișiere Unicode:** Fișierele cu caractere non-ASCII în nume cauzau eșecuri silențioase ale transcrierii în fundal. Remediat prin direcționarea tuturor ieșirilor printr-o cale temporară igienizată bazată pe ID sarcină, apoi mutarea rezultatului la destinația corectă după finalizare.
+
+**SRT în modul fundal:** `spawnDetached` anterior codifica rigid `-otxt` indiferent de formatul solicitat, iar `generate_subtitles` bloca sincron și atingea limita de timp MCP de 4 minute pe fișiere mai lungi. Remediat prin adăugarea parametrului `outputFormat` la `spawnDetached`, suportând ieșire `text` și `srt` în modul fundal.
+
+### ✅ v2.0.1 — Corecții erori (incluse în v2.2.0)
+- `--max-context 0` codificat rigid în `buildArgs` și `spawnDetached` — previne buclele de halucinație pe audio lung.
+- `--no-speech-thold 0.6` codificat rigid în ambele funcții — segmentele sub pragul de încredere sunt tratate ca tăcere.
+- Validare cale (`validateInputPath`) — respinge căile UNC și traversările `..`.
+- Gardă dimensiune fișier `MAX_FILE_SIZE_MB = 10240`.
+- Comentariu securitate injecție transcriere în `transcribeSingle`.
+- Comandă CLI lot coruptă corectată în TROUBLESHOOTING.md.
+
+### ✅ v2.1.0 — Suită de gestionare modele (inclusă în v2.2.0)
+- `WHISPER_MODEL` schimbat din `const` în `let` (mutabil în sesiune).
+- `MODEL_REGISTRY` — 16 modele, variante de precizie completă și cuantizate, URL-uri de descărcare Hugging Face.
+- `ALLOWED_HF_PREFIXES` — lista de permise URL care limitează descărcările la spațiile de nume `ggerganov/whisper.cpp` și `ggml-org`.
+- Instrument `list_models` — scanează directorul de modele, arată modelul activ, dimensiuni, cazuri de utilizare, descărcări disponibile.
+- Instrument `download_model` — descarcă de la Hugging Face prin `https` integrat Node.js, redenumire atomică.
+- Instrument `switch_model` — validează extensia `.bin`, restricție director, verificare blocare proces.
+- `recommendedModel()` actualizat pentru a recomanda `large-v3-turbo` pentru VRAM 6GB+.
+
+### ✅ v2.2.0 — Extindere calitate, parametri și hardware (curent)
+- Interfață `WhisperOptions` înlocuind argumentele poziționale în `buildArgs`.
+- Parametri noi în `transcribe_audio`: `temperature`, `prompt`, `condition_on_prev_text`, `no_speech_thold`, `beam_size`, `best_of`, `gpu_device`, `processors`, `word_timestamps`, `max_segment_length`, `split_on_word`, `diarize`, `vad_model`, `offset_t`, `duration`.
+- Parametri noi în `generate_subtitles`: `temperature`, `prompt`, `beam_size`, `best_of`, `diarize`, `vad_model`.
+- `spawnDetached` refactorizat — toate indicatoarele de calitate sunt acum aplicate în modul fundal/lot.
+- Ieșire lot corectată — `readBatchProgress` acum mută ieșirea temporară la destinația finală înainte de validare.
+
+---
+
+## Bug critic — Avansare automată lot (confirmat, în așteptarea remedierii)
+
+### Lotul nu avansează fără interogare activă
+
+`start_batch` nu avansează autonom coada între fișiere. Lotul avansează doar când este apelat `check_batch_progress`. Fără interogare, lotul se oprește pe termen nedefinit după fiecare fișier.
+
+**Remediere planificată — Opțiunea B (callback ieșire):** Atașează un handler `on('exit')` la procesul copil whisper-cli pornit. Când procesul iese, apelează imediat logica de avansare pentru a valida ieșirea și a porni sarcina următoare.
+
+**Soluție temporară curentă:** Apelează `check_batch_progress` în mod repetat până când lotul se finalizează.
+
+---
+
+## Planificat — Arhitectură confidențialitate (înainte de migrarea la Bun)
+
+### Variabila de mediu `WHISPER_PRIVACY_MODE`
+Adaugă `WHISPER_PRIVACY_MODE` ca variabilă de mediu în `claude_desktop_config.json`. Când este activată, toate răspunsurile instrumentelor returnează doar metadate — niciun text de transcriere nu este inclus.
+
+### Poartă de consimțământ pentru conținut de transcriere
+Când `WHISPER_PRIVACY_MODE` nu este activat (implicit), orice răspuns al instrumentului care include text de transcriere trebuie precedat de o dezvăluire la prima utilizare per sesiune.
+
+### Documentația `PRIVACY.md`
+Creează `PRIVACY.md` în rădăcina depozitului cu îndrumări complete privind confidențialitatea și cadre de conformitate.
+
+### Curățare automată director temporar
+Adaugă curățare automată a fișierelor de sarcini finalizate după o fereastră de retenție configurabilă (implicit: 7 zile).
+
+---
+
+## Planificat — Migrare la Bun
+
+Migrează runtime-ul de la Node.js la [Bun](https://bun.sh) după finalizarea arhitecturii de confidențialitate și înainte de adăugările de funcții v2.3.0. Bun rulează TypeScript nativ fără pas de compilare și pornește semnificativ mai rapid decât Node.
+
+---
+
+## Licențiere
+
+whisper-windows-mcp folosește licențiere duală.
+
+**Utilizare non-comercială:** MIT — gratuit pentru uz personal, educațional și non-comercial. Vezi [LICENSE](LICENSE).
+
+**Utilizare comercială:** Este necesar un acord de licență comercială separat. Vezi [LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md).
+
+`WHISPER_PRIVACY_MODE` pentru implementări în sectoare reglementate este în curs de dezvoltare și planificat pentru o versiune viitoare. Vezi [PRIVACY.md](PRIVACY.md) pentru îndrumări actuale.
+
+## Planificat — v2.3.0: Extindere formate de ieșire
+
+### Format subtitrări VTT
+Ieșire WebVTT (`.vtt`) împreună cu SRT. Standard web folosit de YouTube, HTML5 `<video>` și majoritatea playerelor moderne.
+
+### Format LRC
+Ieșire în format LRC (`.lrc`) versuri/karaoke prin `-olrc`.
+
+### Format CSV
+Ieșire CSV (`.csv`) prin `-ocsv`. Date tabulare structurate cu sincronizare segmente.
+
+---
+
+## Planificat — Versiuni viitoare
+
+### TinyDiarize
+Suport pentru indicatorul `--tinydiarize` cu variante de model care suportă `tdrz`. Funcționează pe înregistrări mono spre deosebire de indicatorul `--diarize` stereo.
+
+### Transcriere URL YouTube
+Transcriere directă din URL-uri YouTube prin yt-dlp. Necesită yt-dlp instalat și în PATH.
+
+### Instrumente flux de lucru proiect video
+Pentru utilizatorii care gestionează proiecte mari de editare video cu directoare de clipuri sursă și editate. Fișierele sursă nu sunt niciodată redenumite sau modificate fără confirmarea explicită a utilizatorului.
+
+### Diarizare vorbitori (pyannote-audio)
+Diarizare completă mono cu etichete ID vorbitor. Necesită pyannote-audio — bibliotecă bazată pe Python cu cerință de token acces modele Hugging Face.
+
+### Traducere în limbi non-engleze
+Indicatorul `--translate` al Whisper țintește doar engleza. Suportarea limbilor țintă arbitrare necesită un API de traducere extern sau un model de traducere local.
+
+### Curățare și formatare transcrieri
+Pipeline de post-procesare: eliminarea cuvintelor de umplutură, pauze de paragraf la granițele naturale ale subiectelor, formatare conștientă de vorbitor, export în PDF sau DOCX.
+
+---
+
+## Distribuție
+
+Disponibil pe [npm](https://www.npmjs.com/package/whisper-windows-mcp), [mcpservers.org](https://mcpservers.org) și [Glama](https://glama.ai).
+
+---
+
+## Documentație multilingvă
+
+Documentația în japoneză, coreeană, vietnameză, indoneziană, ucraineană, portugheză braziliană, spaniolă, poloneză și română este menținută în paralel cu engleza. Următoarele fișiere trebuie actualizate pentru a corespunde documentelor în engleză după fiecare versiune:
+
+**Japoneză (`*.ja.md`)** — `README.ja.md` / `TROUBLESHOOTING.ja.md` / `ROADMAP.ja.md` / `PRIVACY.ja.md` / `SECURITY.ja.md`
+
+**Coreeană (`*.ko.md`)** — `README.ko.md` / `TROUBLESHOOTING.ko.md` / `ROADMAP.ko.md` / `PRIVACY.ko.md` / `SECURITY.ko.md`
+
+**Vietnameză (`*.vi.md`)** — `README.vi.md` / `TROUBLESHOOTING.vi.md` / `ROADMAP.vi.md` / `PRIVACY.vi.md` / `SECURITY.vi.md`
+
+**Indoneziană (`*.id.md`)** — `README.id.md` / `TROUBLESHOOTING.id.md` / `ROADMAP.id.md` / `PRIVACY.id.md` / `SECURITY.id.md`
+
+**Ucraineană (`*.uk.md`)** — `README.uk.md` / `TROUBLESHOOTING.uk.md` / `ROADMAP.uk.md` / `PRIVACY.uk.md` / `SECURITY.uk.md`
+
+**Portugheză braziliană (`*.pt-BR.md`)** — `README.pt-BR.md` / `TROUBLESHOOTING.pt-BR.md` / `ROADMAP.pt-BR.md` / `PRIVACY.pt-BR.md` / `SECURITY.pt-BR.md`
+
+**Spaniolă (`*.es.md`)** — `README.es.md` / `TROUBLESHOOTING.es.md` / `ROADMAP.es.md` / `PRIVACY.es.md` / `SECURITY.es.md`
+
+**Poloneză (`*.pl.md`)** — `README.pl.md` / `TROUBLESHOOTING.pl.md` / `ROADMAP.pl.md` / `PRIVACY.pl.md` / `SECURITY.pl.md`
+
+**Română (`*.ro.md`)** — `README.ro.md` / `TROUBLESHOOTING.ro.md` / `ROADMAP.ro.md` / `PRIVACY.ro.md` / `SECURITY.ro.md`
+
+Contribuțiile comunității pentru alte limbi sunt binevenite.
+
+---
+
+## Contribuții
+
+Pull request-urile sunt binevenite. Verifică issue-urile existente înainte de a începe lucrul.
+
+Dacă ai testat accelerarea GPU pe hardware nelistat mai sus, deschide un issue cu modelul GPU, VRAM, dimensiunea modelului și debitul observat. Aceasta ajută la construirea unei referințe de performanță precise pentru alți utilizatori.