whisper-windows-mcp 2.2.0 → 2.2.2

package/TROUBLESHOOTING.pt-BR.md

@@ -0,0 +1,323 @@
+# whisper-windows-mcp — Solução de Problemas
+
+---
+
+## Lista de verificação rápida
+
+Antes de investigar mais fundo, verifique todos os itens a seguir:
+
+- Caminhos em `claude_desktop_config.json` usam **barras invertidas duplas** (`C:\\whisper\\...`)
+- `whisper-cli.exe` existe no caminho especificado em `WHISPER_CLI_PATH`
+- O arquivo de modelo `.bin` existe no caminho especificado em `WHISPER_MODEL`
+- FFmpeg está instalado e acessível (`ffmpeg -version` funciona no prompt de comando)
+- O Claude Desktop foi **completamente reiniciado** após editar a configuração (saindo da bandeja do sistema, não apenas fechando a janela)
+- O servidor whisper aparece como **em execução** (emblema verde) em Configurações → Desenvolvedor
+
+---
+
+## "whisper não está conectado" ou nenhuma ferramenta disponível
+
+**Causa mais comum:** O Claude Desktop não foi completamente reiniciado após editar a configuração.
+
+1. Clique com o botão direito no ícone do Claude na bandeja do sistema → Sair
+2. Reabra o Claude Desktop
+3. Vá para Configurações → Desenvolvedor e verifique o emblema verde **em execução** ao lado do whisper
+
+Se ainda não aparecer:
+
+1. Abra `claude_desktop_config.json` e verifique erros de sintaxe JSON (vírgulas faltando, chaves não correspondentes)
+2. Certifique-se de que todos os caminhos usam barras invertidas duplas
+3. Execute `check_config` no Claude Desktop para obter um diagnóstico
+
+---
+
+## download_model atinge timeout em modelos grandes
+
+O Claude Desktop tem um timeout de 4 minutos em chamadas de ferramentas MCP. Downloads de modelos grandes em conexões lentas podem exceder esse limite.
+
+**Tamanhos dos arquivos:**
+- `large-v3` — 2,9 GB
+- `large-v3-turbo` — 1,6 GB
+- `large-v3-q5_0` — 1,1 GB
+- `large-v3-turbo-q5_0` — 547 MB
+- `medium.en` — 1,5 GB
+- `medium.en-q5_0` — 514 MB
+
+Em uma conexão rápida (100 Mbps+), até o large-v3 termina em menos de 4 minutos. Em conexões mais lentas, use um navegador ou PowerShell para baixar diretamente e coloque o arquivo no diretório de modelos manualmente:
+
+```powershell
+# Exemplo — baixar large-v3-turbo diretamente
+Invoke-WebRequest -Uri "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin" `
+  -OutFile "C:\whisper\models\ggml-large-v3-turbo.bin"
+```
+
+Depois use `switch_model ggml-large-v3-turbo.bin` para ativá-lo.
+
+---
+
+## `check_config` reporta que whisper-cli.exe não foi encontrado
+
+O caminho na sua configuração não corresponde ao local real do arquivo.
+
+Verifique se o arquivo existe:
+```
+dir C:\whisper\Release\whisper-cli.exe
+```
+
+Se estiver em outro lugar, atualize `WHISPER_CLI_PATH` na sua configuração para corresponder ao caminho real.
+
+---
+
+## `check_config` reporta que FFmpeg não foi encontrado
+
+O FFmpeg não está instalado ou não está no PATH do sistema.
+
+Instale via winget:
+```
+winget install ffmpeg
+```
+
+Ou baixe em [ffmpeg.org](https://ffmpeg.org/download.html), extraia e adicione a pasta `bin` ao PATH do sistema.
+
+Após instalar, abra um novo prompt de comando e verifique:
+```
+ffmpeg -version
+```
+
+Se você instalou o FFmpeg em um local não padrão, defina a variável de ambiente `FFMPEG_PATH` na sua configuração do Claude Desktop:
+```json
+"env": {
+  "FFMPEG_PATH": "C:\\ffmpeg\\bin\\ffmpeg.exe"
+}
+```
+
+---
+
+## A saída da transcrição está cheia de tags `[FOREIGN]`
+
+**Causa:** Você está usando um modelo somente inglês (ex.: `ggml-medium.en.bin`) em áudio que não é inglês. Modelos somente inglês não conseguem processar outros idiomas e geram `[FOREIGN]` como marcador para cada segmento que não conseguem processar.
+
+**Correção:** Baixe e use `ggml-large-v3.bin` — o modelo multilíngue. Isso é necessário para qualquer transcrição que não seja em inglês, detecção automática de idioma ou tradução.
+
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin
+```
+
+Salve em `C:\whisper\models\` e atualize sua configuração:
+```json
+"WHISPER_MODEL": "C:\\whisper\\models\\ggml-large-v3.bin"
+```
+
+Ou substitua por transcrição usando o parâmetro `model` em `transcribe_audio` ou `generate_subtitles`.
+
+> **Nota:** Modelos somente inglês (`*.en.bin`) são mais rápidos e precisos para conteúdo em inglês, mas são completamente incapazes de processar outros idiomas. Se você trabalha com conteúdo multilíngue, `large-v3` é o modelo correto independentemente do hardware.
+
+---
+
+## A transcrição não produz saída ou arquivo vazio
+
+**Possíveis causas:**
+
+1. **Modelo errado para o idioma** — Modelos somente inglês (`*.en.bin`) não conseguem transcrever outros idiomas. Use `ggml-large-v3.bin` para conteúdo multilíngue.
+
+2. **Qualidade de áudio muito baixa** — Arquivos com taxa de bits muito baixa (ex.: gravações antigas de celular `.3gp` usando codec AMR-NB a ~12kbps) podem estar no limite do que o whisper consegue processar. Ambientes ruidosos (ruído de fundo, eco, falantes distantes) também são desafiadores. Tente `large-v3`, que lida melhor com áudio degradado.
+
+3. **Arquivo silencioso ou corrompido** — Execute `analyze_media` no arquivo para verificar se o FFprobe detecta um fluxo de áudio válido.
+
+4. **Falha na conversão** — O arquivo pode não estar sendo convertido para WAV corretamente. Tente converter manualmente primeiro:
+```
+ffmpeg -i yourfile.3gp -ar 16000 -ac 1 output.wav
+```
+Depois transcreva o WAV diretamente.
+
+---
+
+## Tarefa em segundo plano falha em arquivos com caracteres especiais ou Unicode no nome
+
+**Causa:** O whisper-cli.exe não consegue gravar o arquivo de saída quando o caminho contém caracteres Unicode (português, japonês, chinês, emoji, colchetes etc.) ou certos caracteres especiais.
+
+**Solução alternativa atual:** Renomeie o arquivo para usar apenas caracteres ASCII antes de transcrever, depois renomeie de volta se necessário.
+
+```
+ren "arquivo_português.mp4" "temp_transcribe.mp4"
+```
+
+**Status:** Este é um bug conhecido. Uma correção está planejada que roteará a saída por um caminho temporário sanitizado e moverá o resultado para o destino correto após a conclusão.
+
+---
+
+## Tarefa em segundo plano mostra "falha" sem saída
+
+**Possíveis causas:**
+
+1. **Nome de arquivo Unicode** — Veja acima.
+
+2. **Caminho do modelo incorreto** — O processo separado não herda os caminhos corrigidos. Execute `check_config` para verificar os caminhos.
+
+3. **Processo foi encerrado** — Se o whisper-cli.exe foi manualmente encerrado no meio de uma tarefa, nenhum arquivo de saída existirá. Tente novamente.
+
+4. **VRAM insuficiente** — Modelos grandes em GPUs com pouca VRAM podem falhar silenciosamente. Tente um modelo menor.
+
+5. **Falha na conversão do arquivo** — Tente transcrever um arquivo WAV diretamente para isolar se o problema está na conversão ou na transcrição.
+
+---
+
+## A transcrição em segundo plano não produz saída SRT
+
+**Causa:** O modo em segundo plano (`background=true` em `transcribe_audio`) atualmente produz apenas saída `.txt`. O formato SRT no modo em segundo plano ainda não foi implementado.
+
+**Solução alternativa:** Para arquivos abaixo de ~4 minutos, use `generate_subtitles` no modo de bloqueio. Para arquivos mais longos, transcreva primeiro no modo em segundo plano para obter o `.txt`, depois se precisar do SRT, use `generate_subtitles` no mesmo arquivo (ele vai transcrever novamente).
+
+**Status:** O suporte a SRT no modo em segundo plano está planejado para um release futuro.
+
+---
+
+## GPU não está sendo usada (CPU travada acima de 50%)
+
+**Causa:** Você está executando o binário somente CPU que acompanha o release padrão do whisper.cpp.
+
+**Correção:** Baixe a build com Vulkan ativado da [página de releases](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) e extraia para `C:\whisper\Release\`.
+
+Verifique se a aceleração GPU está ativa:
+- Peça ao Claude para executar `check_system`
+- Procure `✅ Vulkan binary: ggml-vulkan.dll found` na saída
+- Observe o Gerenciador de Tarefas → Desempenho → GPU durante uma transcrição — a utilização da GPU deve subir para 15–30%
+
+---
+
+## `check_system` reporta quantidade de VRAM incorreta
+
+Esta é uma limitação conhecida do Windows. O comando `wmic` lê a VRAM do registro, que em muitas placas AMD reporta metade da VRAM física. Uma Vega 56 com 8GB HBM2 normalmente mostrará 4GB. Este é apenas um problema de exibição — o whisper usa toda a VRAM física durante a inferência.
+
+---
+
+## Erro "Transcrição já em andamento"
+
+Um processo `whisper-cli.exe` está sendo executado de uma tarefa anterior. Aguarde-o terminar, ou:
+
+1. Abra o Gerenciador de Tarefas → aba Detalhes
+2. Encontre `whisper-cli.exe`
+3. Clique com o botão direito → Encerrar tarefa
+
+Depois tente novamente.
+
+---
+
+## Detecção automática de idioma incorreta
+
+A detecção automática do Whisper é executada nos primeiros 30 segundos do áudio. Se o arquivo começar em um idioma diferente da maior parte do seu conteúdo, a detecção pode estar errada.
+
+**Correção:** Especifique o idioma explicitamente (ex.: `language=pt`) em vez de depender da detecção automática.
+
+---
+
+## A geração de legendas produz "(falando em língua estrangeira)" em todo o vídeo
+
+O Whisper detectou fala mas não conseguiu transcrever. Causas mais comuns:
+
+1. **Modelo errado** — Usando um modelo somente inglês em áudio que não é inglês. Use `large-v3`.
+
+2. **Qualidade do áudio** — Ambientes ruidosos (cozinhas, multidões, eco) podem superar o modelo medium. Tente `large-v3`.
+
+3. **Idioma misto** — Arquivos com dois idiomas alternando terão o idioma minoritário substituído por marcadores com configuração de idioma único.
+
+---
+
+## A tradução de legendas só produz inglês
+
+Este é o comportamento esperado. O flag `--translate` integrado do Whisper traduz apenas **para o inglês**. Para tradução para outros idiomas de destino, processe o conteúdo do arquivo `.srt` separadamente.
+
+---
+
+## A transcrição em lote parou de avançar
+
+Chame `check_batch_progress` novamente. Se ainda estiver travado:
+
+1. Verifique no Gerenciador de Tarefas se há um processo `whisper-cli.exe` em execução
+2. Verifique os logs de tarefas em `%TEMP%\whisper-mcp-jobs\`
+3. Arquivos com falha são sinalizados no relatório do lote — execute-os individualmente com `transcribe_audio`
+
+---
+
+## Limpando o diretório temporário de tarefas
+
+O whisper-windows-mcp grava arquivos de estado de tarefas e logs em `%TEMP%\whisper-mcp-jobs\` durante a transcrição. Eles se acumulam ao longo do tempo e podem consumir espaço em disco, especialmente os arquivos `.log` de tarefas de transcrição longas.
+
+Depois que um lote ou tarefa estiver concluído e você tiver verificado as transcrições de saída, você pode excluir com segurança tudo neste diretório:
+
+```powershell
+Remove-Item "$env:TEMP\whisper-mcp-jobs\*" -Recurse -Force
+```
+
+O diretório será recriado automaticamente na próxima transcrição. Nenhum arquivo de saída de transcrição é armazenado permanentemente aqui — eles são movidos para o diretório de origem na conclusão. Apenas metadados de tarefas e logs permanecem.
+
+**Nota:** Não exclua este diretório enquanto uma transcrição estiver em andamento — os arquivos de estado do lote são necessários para que `check_batch_progress` funcione.
+
+---
+
+## Lote grande sem supervisão pela linha de comando
+
+Para lotes muito grandes onde você quer executar durante a noite sem o Claude, use o PowerShell.
+
+**Importante:** O whisper-cli.exe não consegue ler MP4, MKV ou a maioria dos formatos de vídeo diretamente. O FFmpeg deve pré-converter cada arquivo para WAV primeiro. O whisper também grava a transcrição no stdout e a saída de diagnóstico no stderr — use `Start-Process -RedirectStandardOutput` para capturar a transcrição corretamente. Usar pipe com `|` ou redirecionar stderr com `2>$null` não captura nada.
+
+```powershell
+$whisper = "C:\whisper\Release\whisper-cli.exe"
+$model   = "C:\whisper\models\ggml-medium.en.bin"
+$dir     = "C:\path\to\your\folder"
+$ffmpeg  = "ffmpeg"
+$tmp     = "$env:TEMP\whisper_convert.wav"
+
+Get-ChildItem "$dir\*.mp4" | ForEach-Object {
+    $out = ($_.FullName -replace '\.mp4$', '') + ".txt"
+    if (Test-Path $out) {
+        Write-Host "SKIP (exists): $($_.Name)"
+        return
+    }
+    Write-Host "Converting:    $($_.Name)"
+    & $ffmpeg -y -i $_.FullName -ar 16000 -ac 1 -c:a pcm_s16le $tmp 2>$null
+    Write-Host "Transcribing:  $($_.Name)"
+    $wArgs = "-m `"$model`" -f `"$tmp`" --threads 8 --condition-on-previous-text 0 --no-speech-thold 0.6"
+    Start-Process -FilePath $whisper -ArgumentList $wArgs -RedirectStandardOutput $out -Wait -NoNewWindow
+    Write-Host "Done:          $($_.BaseName).txt"
+}
+
+Remove-Item $tmp -ErrorAction SilentlyContinue
+Write-Host "All done."
+```
+
+Altere `*.mp4` para `*.mkv`, `*.m4a` etc. para corresponder aos seus tipos de arquivo. A verificação de pulo `Test-Path` significa que executar novamente o script após uma interrupção não reprocessará arquivos já concluídos.
+
+Isso grava arquivos `.txt` ao lado de cada fonte. As ferramentas MCP os reconhecerão como já transcritos quando você executar `analyze_media` ou `start_batch` depois.
+
+---
+
+## Local do arquivo de configuração
+
+```
+C:\Users\SeuUsuário\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+Se `AppData` não estiver visível: Exibir → Mostrar → Itens ocultos no Explorador de Arquivos.
+
+---
+
+## Exemplo de configuração completa funcionando
+
+```json
+{
+  "mcpServers": {
+    "whisper": {
+      "command": "npx",
+      "args": ["-y", "whisper-windows-mcp"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-medium.en.bin",
+        "FFMPEG_PATH": "ffmpeg"
+      }
+    }
+  }
+}
+```
+
+`FFMPEG_PATH` tem como padrão `ffmpeg` (assume que está no PATH). Defina explicitamente apenas se o FFmpeg estiver instalado em um local não padrão.

package/TROUBLESHOOTING.ro.md

@@ -0,0 +1,323 @@
+# whisper-windows-mcp — Depanare
+
+---
+
+## Listă de verificare rapidă
+
+Înainte de a investiga mai profund, verifică toate punctele de mai jos:
+
+- Căile din `claude_desktop_config.json` folosesc **bare oblice inverse duble** (`C:\\whisper\\...`)
+- `whisper-cli.exe` există la calea specificată în `WHISPER_CLI_PATH`
+- Fișierul model `.bin` există la calea specificată în `WHISPER_MODEL`
+- FFmpeg este instalat și accesibil (`ffmpeg -version` funcționează în linia de comandă)
+- Claude Desktop a fost **repornit complet** după editarea configurației (ieșit din bara de sistem, nu doar închis fereastra)
+- Serverul whisper apare ca **în execuție** (insignă verde) în Setări → Dezvoltator
+
+---
+
+## "whisper nu este conectat" sau niciun instrument disponibil
+
+**Cauza cea mai frecventă:** Claude Desktop nu a fost repornit complet după editarea configurației.
+
+1. Fă clic dreapta pe pictograma Claude din bara de sistem → Ieși
+2. Redeschide Claude Desktop
+3. Mergi la Setări → Dezvoltator și verifică insigna verde **în execuție** de lângă whisper
+
+Dacă tot nu apare:
+
+1. Deschide `claude_desktop_config.json` și verifică erorile de sintaxă JSON (virgule lipsă, acolade nepotrivite)
+2. Asigură-te că toate căile folosesc bare oblice inverse duble
+3. Rulează `check_config` în Claude Desktop pentru a obține o diagnosticare
+
+---
+
+## download_model atinge limita de timp pentru modele mari
+
+Claude Desktop are o limită de timp de 4 minute pentru apelurile instrumentelor MCP. Descărcările de modele mari pe conexiuni lente pot depăși acest lucru.
+
+**Dimensiunile fișierelor:**
+- `large-v3` — 2,9 GB
+- `large-v3-turbo` — 1,6 GB
+- `large-v3-q5_0` — 1,1 GB
+- `large-v3-turbo-q5_0` — 547 MB
+- `medium.en` — 1,5 GB
+- `medium.en-q5_0` — 514 MB
+
+Pe o conexiune rapidă (100 Mbps+), chiar și large-v3 se descarcă în mai puțin de 4 minute. Pe conexiuni mai lente, folosește un browser sau PowerShell pentru a descărca direct și plasează fișierul în directorul de modele manual:
+
+```powershell
+# Exemplu — descărcare directă large-v3-turbo
+Invoke-WebRequest -Uri "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin" `
+  -OutFile "C:\whisper\models\ggml-large-v3-turbo.bin"
+```
+
+Apoi folosește `switch_model ggml-large-v3-turbo.bin` pentru activare.
+
+---
+
+## `check_config` raportează că whisper-cli.exe nu a fost găsit
+
+Calea din configurația ta nu corespunde locației reale a fișierului.
+
+Verifică dacă fișierul există:
+```
+dir C:\whisper\Release\whisper-cli.exe
+```
+
+Dacă este altundeva, actualizează `WHISPER_CLI_PATH` în configurația ta pentru a corespunde căii reale.
+
+---
+
+## `check_config` raportează că FFmpeg nu a fost găsit
+
+FFmpeg nu este instalat sau nu este în PATH-ul sistemului.
+
+Instalare via winget:
+```
+winget install ffmpeg
+```
+
+Sau descarcă de la [ffmpeg.org](https://ffmpeg.org/download.html), extrage și adaugă folderul `bin` la PATH-ul sistemului.
+
+După instalare, deschide o nouă linie de comandă și verifică:
+```
+ffmpeg -version
+```
+
+Dacă ai instalat FFmpeg într-o locație non-standard, setează variabila de mediu `FFMPEG_PATH` în configurația Claude Desktop:
+```json
+"env": {
+  "FFMPEG_PATH": "C:\\ffmpeg\\bin\\ffmpeg.exe"
+}
+```
+
+---
+
+## Ieșirea transcrierii este plină de etichete `[FOREIGN]`
+
+**Cauza:** Folosești un model numai engleză (ex.: `ggml-medium.en.bin`) pe audio în altă limbă decât engleza. Modelele numai engleză nu pot procesa alte limbi și generează `[FOREIGN]` ca substituent pentru fiecare segment pe care nu îl pot gestiona.
+
+**Soluție:** Descarcă și folosește `ggml-large-v3.bin` — modelul multilingv. Acesta este necesar pentru orice transcriere non-engleză, detectarea automată a limbii sau traducere.
+
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin
+```
+
+Salvează în `C:\whisper\models\` și actualizează configurația:
+```json
+"WHISPER_MODEL": "C:\\whisper\\models\\ggml-large-v3.bin"
+```
+
+Sau suprascrie per-transcriere folosind parametrul `model` în `transcribe_audio` sau `generate_subtitles`.
+
+> **Notă:** Modelele numai engleză (`*.en.bin`) sunt mai rapide și mai precise pentru conținut în engleză, dar sunt complet incapabile să gestioneze alte limbi. Dacă lucrezi cu conținut multilingv, `large-v3` este modelul corect indiferent de hardware.
+
+---
+
+## Transcrierea nu produce ieșire sau fișier gol
+
+**Cauze posibile:**
+
+1. **Model greșit pentru limbă** — Modelele numai engleză (`*.en.bin`) nu pot transcriere alte limbi. Folosește `ggml-large-v3.bin` pentru conținut multilingv.
+
+2. **Calitate audio prea scăzută** — Fișierele cu rată de biți foarte mică (ex.: înregistrări vechi de telefon `.3gp` folosind codec AMR-NB ~12kbps) pot fi la limita a ceea ce whisper poate procesa. Mediile zgomotoase (zgomot de fundal, ecou, vorbitori depărtați) sunt de asemenea dificile. Încearcă `large-v3` care gestionează mai bine audio degradat.
+
+3. **Fișier silențios sau corupt** — Rulează `analyze_media` pe fișier pentru a verifica dacă FFprobe detectează un flux audio valid.
+
+4. **Eșec de conversie** — Fișierul poate să nu se convertească corect la WAV. Încearcă să convertești manual mai întâi:
+```
+ffmpeg -i yourfile.3gp -ar 16000 -ac 1 output.wav
+```
+Apoi transcrie WAV-ul direct.
+
+---
+
+## Sarcina în fundal eșuează pe fișiere cu caractere speciale sau Unicode în nume
+
+**Cauza:** whisper-cli.exe nu poate scrie fișierul de ieșire când calea conține caractere Unicode (română, japoneză, chineză, emoji, paranteze etc.) sau anumite caractere speciale.
+
+**Soluție temporară curentă:** Redenumește fișierul pentru a folosi doar caractere ASCII înainte de transcriere, apoi redenumește înapoi dacă este necesar.
+
+```
+ren "fisier_romanesc.mp4" "temp_transcribe.mp4"
+```
+
+**Status:** Acesta este un bug cunoscut. O corecție este planificată care va direcționa ieșirea printr-o cale temporară igienizată și va muta rezultatul la destinația corectă după finalizare.
+
+---
+
+## Sarcina în fundal arată "eșuat" fără ieșire
+
+**Cauze posibile:**
+
+1. **Nume de fișier Unicode** — Vezi mai sus.
+
+2. **Cale model greșită** — Procesul detașat nu moștenește căile corectate. Rulează `check_config` pentru a verifica căile.
+
+3. **Procesul a fost terminat** — Dacă whisper-cli.exe a fost terminat manual în mijlocul unei sarcini, nu va exista niciun fișier de ieșire. Încearcă din nou.
+
+4. **VRAM insuficient** — Modelele mari pe GPU-uri cu VRAM redus pot eșua silențios. Încearcă un model mai mic.
+
+5. **Eșec de conversie a fișierului** — Încearcă să transcrii direct un fișier WAV pentru a izola dacă problema este la conversie sau transcriere.
+
+---
+
+## Transcrierea în fundal nu produce ieșire SRT
+
+**Cauza:** Modul în fundal (`background=true` în `transcribe_audio`) produce în prezent doar ieșire `.txt`. Formatul SRT în modul fundal nu a fost încă implementat.
+
+**Soluție temporară:** Pentru fișiere sub ~4 minute, folosește `generate_subtitles` în modul de blocare. Pentru fișiere mai lungi, transcrie mai întâi în modul fundal pentru a obține `.txt`, apoi dacă este nevoie de SRT, folosește `generate_subtitles` pe același fișier (va transcriere din nou).
+
+**Status:** Suportul SRT în modul fundal este planificat pentru o versiune viitoare.
+
+---
+
+## GPU-ul nu este folosit (CPU blocat peste 50%)
+
+**Cauza:** Rulezi binarul numai CPU care vine cu versiunea standard whisper.cpp.
+
+**Soluție:** Descarcă compilarea cu Vulkan activat de pe [pagina de versiuni](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) și extrage în `C:\whisper\Release\`.
+
+Verifică că accelerarea GPU este activă:
+- Cere lui Claude să ruleze `check_system`
+- Caută `✅ Vulkan binary: ggml-vulkan.dll found` în ieșire
+- Urmărește Task Manager → Performanță → GPU în timpul unei transcrieri — utilizarea GPU ar trebui să urce la 15–30%
+
+---
+
+## `check_system` raportează cantitatea greșită de VRAM
+
+Aceasta este o limitare cunoscută Windows. Comanda `wmic` citește VRAM din registry, care pe multe plăci AMD raportează jumătate din VRAM-ul fizic. Un Vega 56 cu 8GB HBM2 va arăta de obicei 4GB. Aceasta este doar o problemă de afișare — whisper folosește tot VRAM-ul fizic în timpul inferenței.
+
+---
+
+## Eroarea "Transcrierea este deja în curs"
+
+Un proces `whisper-cli.exe` rulează dintr-o sarcină anterioară. Așteaptă să se termine, sau:
+
+1. Deschide Task Manager → fila Detalii
+2. Găsește `whisper-cli.exe`
+3. Fă clic dreapta → Încheie sarcina
+
+Apoi încearcă din nou.
+
+---
+
+## Detectarea automată a limbii este greșită
+
+Detectarea automată a Whisper rulează pe primele 30 de secunde de audio. Dacă fișierul începe într-o limbă diferită față de cea mai mare parte a conținutului său, detectarea poate fi greșită.
+
+**Soluție:** Specifică limba explicit (ex.: `language=ro`) în loc să te bazezi pe detectarea automată.
+
+---
+
+## Generarea subtitrărilor produce "(vorbind în limbă străină)" pe tot videoclipul
+
+Whisper a detectat vorbire, dar nu a putut transcriere. Cele mai frecvente cauze:
+
+1. **Model greșit** — Folosind un model numai engleză pe audio non-englezesc. Folosește `large-v3`.
+
+2. **Calitate audio** — Mediile zgomotoase (bucătării, mulțimi, ecou) pot depăși modelul medium. Încearcă `large-v3`.
+
+3. **Limbă mixtă** — Fișierele cu două limbi alternante vor avea limba minoritară înlocuită cu substituenți cu setare de limbă unică.
+
+---
+
+## Traducerea subtitrărilor produce doar engleză
+
+Acesta este comportamentul intenționat. Indicatorul `--translate` integrat al Whisper traduce doar **în engleză**. Pentru traducere în alte limbi țintă, procesează conținutul fișierului `.srt` separat.
+
+---
+
+## Transcrierea în lot a încetat să avanseze
+
+Apelează din nou `check_batch_progress`. Dacă tot este blocată:
+
+1. Verifică Task Manager pentru un proces `whisper-cli.exe` care rulează
+2. Verifică jurnalele sarcinilor în `%TEMP%\whisper-mcp-jobs\`
+3. Fișierele cu erori sunt marcate în raportul lotului — rulează-le individual cu `transcribe_audio`
+
+---
+
+## Curățarea directorului temporar de sarcini
+
+whisper-windows-mcp scrie fișiere de stare a sarcinilor și jurnale în `%TEMP%\whisper-mcp-jobs\` în timpul transcrierii. Acestea se acumulează în timp și pot consuma spațiu pe disc, în special fișierele `.log` din sarcinile lungi de transcriere.
+
+Odată ce un lot sau o sarcină este finalizată și ai verificat transcrierile de ieșire, poți șterge în siguranță totul din acest director:
+
+```powershell
+Remove-Item "$env:TEMP\whisper-mcp-jobs\*" -Recurse -Force
+```
+
+Directorul va fi recreat automat la următoarea transcriere. Niciun fișier de ieșire a transcrierii nu este stocat permanent aici — sunt mutate în directorul sursă la finalizare. Rămân doar metadate ale sarcinilor și jurnale.
+
+**Notă:** Nu șterge acest director în timp ce o transcriere este în curs — fișierele de stare a lotului sunt necesare pentru funcționarea `check_batch_progress`.
+
+---
+
+## Lot mare nesupravegheit din linia de comandă
+
+Pentru loturi foarte mari în care vrei să rulezi peste noapte fără Claude, folosește PowerShell.
+
+**Important:** whisper-cli.exe nu poate citi direct MP4, MKV sau majoritatea formatelor video. FFmpeg trebuie să preconvertească fiecare fișier la WAV mai întâi. Whisper scrie de asemenea transcrierea la stdout și ieșirea de diagnosticare la stderr — folosește `Start-Process -RedirectStandardOutput` pentru a capta corect transcrierea. Folosirea pipe `|` sau redirecționarea stderr cu `2>$null` nu capturează nimic.
+
+```powershell
+$whisper = "C:\whisper\Release\whisper-cli.exe"
+$model   = "C:\whisper\models\ggml-medium.en.bin"
+$dir     = "C:\path\to\your\folder"
+$ffmpeg  = "ffmpeg"
+$tmp     = "$env:TEMP\whisper_convert.wav"
+
+Get-ChildItem "$dir\*.mp4" | ForEach-Object {
+    $out = ($_.FullName -replace '\.mp4$', '') + ".txt"
+    if (Test-Path $out) {
+        Write-Host "SKIP (exists): $($_.Name)"
+        return
+    }
+    Write-Host "Converting:    $($_.Name)"
+    & $ffmpeg -y -i $_.FullName -ar 16000 -ac 1 -c:a pcm_s16le $tmp 2>$null
+    Write-Host "Transcribing:  $($_.Name)"
+    $wArgs = "-m `"$model`" -f `"$tmp`" --threads 8 --condition-on-previous-text 0 --no-speech-thold 0.6"
+    Start-Process -FilePath $whisper -ArgumentList $wArgs -RedirectStandardOutput $out -Wait -NoNewWindow
+    Write-Host "Done:          $($_.BaseName).txt"
+}
+
+Remove-Item $tmp -ErrorAction SilentlyContinue
+Write-Host "All done."
+```
+
+Schimbă `*.mp4` cu `*.mkv`, `*.m4a` etc. pentru a corespunde tipurilor tale de fișiere. Verificarea de sărire `Test-Path` înseamnă că rularea din nou a scriptului după o întrerupere nu va reprocesa fișierele deja finalizate.
+
+Aceasta scrie fișiere `.txt` lângă fiecare sursă. Instrumentele MCP le vor recunoaște ca deja transcrise când rulezi ulterior `analyze_media` sau `start_batch`.
+
+---
+
+## Locația fișierului de configurare
+
+```
+C:\Users\NumeUtilizator\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+Dacă `AppData` nu este vizibil: Vizualizare → Afișare → Elemente ascunse în File Explorer.
+
+---
+
+## Exemplu de configurare completă funcțională
+
+```json
+{
+  "mcpServers": {
+    "whisper": {
+      "command": "npx",
+      "args": ["-y", "whisper-windows-mcp"],
+      "env": {
+        "WHISPER_CLI_PATH": "C:\\whisper\\Release\\whisper-cli.exe",
+        "WHISPER_MODEL": "C:\\whisper\\models\\ggml-medium.en.bin",
+        "FFMPEG_PATH": "ffmpeg"
+      }
+    }
+  }
+}
+```
+
+`FFMPEG_PATH` are implicit valoarea `ffmpeg` (presupune că este în PATH). Setează explicit doar dacă FFmpeg este instalat într-o locație non-standard.