whisper-windows-mcp 2.2.0 → 2.2.2

package/TROUBLESHOOTING.es.md

@@ -0,0 +1,323 @@
+# whisper-windows-mcp — Solución de Problemas
+
+---
+
+## Lista de verificación rápida
+
+Antes de investigar más a fondo, verifica todos los siguientes puntos:
+
+- Las rutas en `claude_desktop_config.json` usan **barras invertidas dobles** (`C:\\whisper\\...`)
+- `whisper-cli.exe` existe en la ruta especificada en `WHISPER_CLI_PATH`
+- El archivo de modelo `.bin` existe en la ruta especificada en `WHISPER_MODEL`
+- FFmpeg está instalado y accesible (`ffmpeg -version` funciona en el símbolo del sistema)
+- Claude Desktop fue **completamente reiniciado** tras editar la configuración (saliendo desde la bandeja del sistema, no solo cerrando la ventana)
+- El servidor whisper aparece como **en ejecución** (insignia verde) en Configuración → Desarrollador
+
+---
+
+## "whisper no está conectado" o no hay herramientas disponibles
+
+**Causa más común:** Claude Desktop no fue completamente reiniciado tras editar la configuración.
+
+1. Clic derecho en el ícono de Claude en la bandeja del sistema → Salir
+2. Vuelve a abrir Claude Desktop
+3. Ve a Configuración → Desarrollador y verifica la insignia verde **en ejecución** junto a whisper
+
+Si sigue sin aparecer:
+
+1. Abre `claude_desktop_config.json` y verifica errores de sintaxis JSON (comas faltantes, llaves no coincidentes)
+2. Asegúrate de que todas las rutas usen barras invertidas dobles
+3. Ejecuta `check_config` en Claude Desktop para obtener un diagnóstico
+
+---
+
+## download_model alcanza timeout en modelos grandes
+
+Claude Desktop tiene un timeout de 4 minutos en las llamadas a herramientas MCP. Las descargas de modelos grandes en conexiones lentas pueden exceder este límite.
+
+**Tamaños de archivo:**
+- `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
+
+En una conexión rápida (100 Mbps+), incluso large-v3 termina en menos de 4 minutos. En conexiones más lentas, usa un navegador o PowerShell para descargar directamente y coloca el archivo en tu directorio de modelos manualmente:
+
+```powershell
+# Ejemplo — descargar large-v3-turbo directamente
+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"
+```
+
+Luego usa `switch_model ggml-large-v3-turbo.bin` para activarlo.
+
+---
+
+## `check_config` reporta que whisper-cli.exe no fue encontrado
+
+La ruta en tu configuración no coincide con la ubicación real del archivo.
+
+Verifica que el archivo existe:
+```
+dir C:\whisper\Release\whisper-cli.exe
+```
+
+Si está en otro lugar, actualiza `WHISPER_CLI_PATH` en tu configuración para que coincida con la ruta real.
+
+---
+
+## `check_config` reporta que FFmpeg no fue encontrado
+
+FFmpeg no está instalado o no está en el PATH del sistema.
+
+Instala via winget:
+```
+winget install ffmpeg
+```
+
+O descarga desde [ffmpeg.org](https://ffmpeg.org/download.html), extrae y agrega la carpeta `bin` al PATH del sistema.
+
+Tras instalar, abre un nuevo símbolo del sistema y verifica:
+```
+ffmpeg -version
+```
+
+Si instalaste FFmpeg en una ubicación no estándar, establece la variable de entorno `FFMPEG_PATH` en tu configuración de Claude Desktop:
+```json
+"env": {
+  "FFMPEG_PATH": "C:\\ffmpeg\\bin\\ffmpeg.exe"
+}
+```
+
+---
+
+## La salida de transcripción está llena de etiquetas `[FOREIGN]`
+
+**Causa:** Estás usando un modelo solo inglés (ej.: `ggml-medium.en.bin`) en audio que no es inglés. Los modelos solo inglés no pueden procesar otros idiomas y generan `[FOREIGN]` como marcador para cada segmento que no pueden manejar.
+
+**Solución:** Descarga y usa `ggml-large-v3.bin` — el modelo multilingüe. Esto es necesario para cualquier transcripción que no sea inglés, detección automática de idioma o traducción.
+
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin
+```
+
+Guarda en `C:\whisper\models\` y actualiza tu configuración:
+```json
+"WHISPER_MODEL": "C:\\whisper\\models\\ggml-large-v3.bin"
+```
+
+O anula por transcripción usando el parámetro `model` en `transcribe_audio` o `generate_subtitles`.
+
+> **Nota:** Los modelos solo inglés (`*.en.bin`) son más rápidos y precisos para contenido en inglés, pero son completamente incapaces de manejar otros idiomas. Si trabajas con contenido multilingüe, `large-v3` es el modelo correcto independientemente del hardware.
+
+---
+
+## La transcripción no produce salida o el archivo está vacío
+
+**Posibles causas:**
+
+1. **Modelo incorrecto para el idioma** — Los modelos solo inglés (`*.en.bin`) no pueden transcribir otros idiomas. Usa `ggml-large-v3.bin` para contenido multilingüe.
+
+2. **Calidad de audio muy baja** — Los archivos con tasa de bits muy baja (ej.: grabaciones antiguas de celular `.3gp` usando códec AMR-NB a ~12kbps) pueden estar en el límite de lo que whisper puede procesar. Los entornos ruidosos (ruido de fondo, eco, hablantes distantes) también son desafiantes. Prueba `large-v3`, que maneja mejor el audio degradado.
+
+3. **Archivo silencioso o corrupto** — Ejecuta `analyze_media` en el archivo para verificar si FFprobe detecta un flujo de audio válido.
+
+4. **Fallo en la conversión** — El archivo puede no estar convirtiéndose a WAV correctamente. Intenta convertir manualmente primero:
+```
+ffmpeg -i yourfile.3gp -ar 16000 -ac 1 output.wav
+```
+Luego transcribe el WAV directamente.
+
+---
+
+## La tarea en segundo plano falla en archivos con caracteres especiales o Unicode en el nombre
+
+**Causa:** whisper-cli.exe no puede escribir el archivo de salida cuando la ruta contiene caracteres Unicode (español, japonés, chino, emoji, corchetes, etc.) o ciertos caracteres especiales.
+
+**Solución alternativa actual:** Renombra el archivo para usar solo caracteres ASCII antes de transcribir, luego renombra de vuelta si es necesario.
+
+```
+ren "archivo_español.mp4" "temp_transcribe.mp4"
+```
+
+**Estado:** Este es un bug conocido. Hay una corrección planificada que enrutará la salida a través de una ruta temporal saneada y moverá el resultado al destino correcto tras completarse.
+
+---
+
+## La tarea en segundo plano muestra "fallo" sin salida
+
+**Posibles causas:**
+
+1. **Nombre de archivo Unicode** — Ver arriba.
+
+2. **Ruta del modelo incorrecta** — El proceso separado no hereda las rutas corregidas. Ejecuta `check_config` para verificar las rutas.
+
+3. **Proceso fue terminado** — Si whisper-cli.exe fue terminado manualmente a mitad de una tarea, no existirá ningún archivo de salida. Vuelve a intentarlo.
+
+4. **VRAM insuficiente** — Los modelos grandes en GPUs con poca VRAM pueden fallar silenciosamente. Prueba un modelo más pequeño.
+
+5. **Fallo en la conversión del archivo** — Intenta transcribir un archivo WAV directamente para aislar si el problema está en la conversión o en la transcripción.
+
+---
+
+## La transcripción en segundo plano no produce salida SRT
+
+**Causa:** El modo en segundo plano (`background=true` en `transcribe_audio`) actualmente solo produce salida `.txt`. El formato SRT en modo en segundo plano aún no ha sido implementado.
+
+**Solución alternativa:** Para archivos de menos de ~4 minutos, usa `generate_subtitles` en modo de bloqueo. Para archivos más largos, transcribe primero en modo en segundo plano para obtener el `.txt`, luego si necesitas el SRT, usa `generate_subtitles` en el mismo archivo (volverá a transcribir).
+
+**Estado:** El soporte de SRT en modo en segundo plano está planificado para un release futuro.
+
+---
+
+## La GPU no está siendo usada (CPU atascada por encima del 50%)
+
+**Causa:** Estás ejecutando el binario solo CPU que viene con el release estándar de whisper.cpp.
+
+**Solución:** Descarga la build con Vulkan activado desde la [página de releases](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) y extrae en `C:\whisper\Release\`.
+
+Verifica que la aceleración GPU está activa:
+- Pide a Claude ejecutar `check_system`
+- Busca `✅ Vulkan binary: ggml-vulkan.dll found` en la salida
+- Observa el Administrador de Tareas → Rendimiento → GPU durante una transcripción — la utilización de GPU debería subir al 15–30%
+
+---
+
+## `check_system` reporta cantidad de VRAM incorrecta
+
+Esta es una limitación conocida de Windows. El comando `wmic` lee la VRAM del registro, que en muchas tarjetas AMD reporta la mitad de la VRAM física. Una Vega 56 con 8GB HBM2 típicamente mostrará 4GB. Esto es solo un problema de visualización — whisper usa toda la VRAM física durante la inferencia.
+
+---
+
+## Error "Transcripción ya en progreso"
+
+Hay un proceso `whisper-cli.exe` ejecutándose de una tarea anterior. Espera a que termine, o:
+
+1. Abre el Administrador de Tareas → pestaña Detalles
+2. Encuentra `whisper-cli.exe`
+3. Clic derecho → Finalizar tarea
+
+Luego vuelve a intentarlo.
+
+---
+
+## La detección automática de idioma es incorrecta
+
+La detección automática de Whisper se ejecuta en los primeros 30 segundos del audio. Si el archivo comienza en un idioma diferente al de la mayoría de su contenido, la detección puede ser incorrecta.
+
+**Solución:** Especifica el idioma explícitamente (ej.: `language=es`) en lugar de depender de la detección automática.
+
+---
+
+## La generación de subtítulos produce "(hablando en idioma extranjero)" en todo el video
+
+Whisper detectó habla pero no pudo transcribir. Causas más comunes:
+
+1. **Modelo incorrecto** — Usando un modelo solo inglés en audio que no es inglés. Usa `large-v3`.
+
+2. **Calidad de audio** — Los entornos ruidosos (cocinas, multitudes, eco) pueden superar al modelo medium. Prueba `large-v3`.
+
+3. **Idioma mixto** — Los archivos con dos idiomas alternando tendrán el idioma minoritario reemplazado por marcadores con una configuración de idioma único.
+
+---
+
+## La traducción de subtítulos solo produce inglés
+
+Este es el comportamiento esperado. El flag `--translate` integrado de Whisper solo traduce **al inglés**. Para traducción a otros idiomas de destino, procesa el contenido del archivo `.srt` por separado.
+
+---
+
+## La transcripción por lotes dejó de avanzar
+
+Llama a `check_batch_progress` nuevamente. Si sigue atascado:
+
+1. Verifica en el Administrador de Tareas si hay un proceso `whisper-cli.exe` en ejecución
+2. Revisa los logs de tareas en `%TEMP%\whisper-mcp-jobs\`
+3. Los archivos con error están marcados en el informe del lote — ejecútalos individualmente con `transcribe_audio`
+
+---
+
+## Limpiar el directorio temporal de tareas
+
+whisper-windows-mcp escribe archivos de estado de tareas y logs en `%TEMP%\whisper-mcp-jobs\` durante la transcripción. Estos se acumulan con el tiempo y pueden consumir espacio en disco, especialmente los archivos `.log` de tareas de transcripción largas.
+
+Una vez que un lote o tarea esté completo y hayas verificado las transcripciones de salida, puedes eliminar de forma segura todo en este directorio:
+
+```powershell
+Remove-Item "$env:TEMP\whisper-mcp-jobs\*" -Recurse -Force
+```
+
+El directorio se recreará automáticamente en la siguiente transcripción. Ningún archivo de salida de transcripción se almacena permanentemente aquí — se mueven al directorio de origen al completarse. Solo quedan metadatos de tareas y logs.
+
+**Nota:** No elimines este directorio mientras una transcripción esté en progreso — los archivos de estado del lote son necesarios para que `check_batch_progress` funcione.
+
+---
+
+## Lote grande sin supervisión desde la línea de comandos
+
+Para lotes muy grandes donde quieres ejecutar durante la noche sin Claude, usa PowerShell.
+
+**Importante:** whisper-cli.exe no puede leer MP4, MKV ni la mayoría de los formatos de video directamente. FFmpeg debe pre-convertir cada archivo a WAV primero. Whisper también escribe la transcripción al stdout y la salida de diagnóstico al stderr — usa `Start-Process -RedirectStandardOutput` para capturar la transcripción correctamente. Usar pipe con `|` o redirigir stderr con `2>$null` no 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."
+```
+
+Cambia `*.mp4` por `*.mkv`, `*.m4a` etc. para que coincida con tus tipos de archivo. La verificación de salto `Test-Path` significa que volver a ejecutar el script tras una interrupción no reprocesará los archivos ya completados.
+
+Esto escribe archivos `.txt` junto a cada fuente. Las herramientas MCP los reconocerán como ya transcritos cuando ejecutes `analyze_media` o `start_batch` después.
+
+---
+
+## Ubicación del archivo de configuración
+
+```
+C:\Users\TuUsuario\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+Si `AppData` no es visible: Ver → Mostrar → Elementos ocultos en el Explorador de archivos.
+
+---
+
+## Ejemplo de configuración 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` tiene como predeterminado `ffmpeg` (asume que está en el PATH). Establécelo explícitamente solo si FFmpeg está instalado en una ubicación no estándar.

package/TROUBLESHOOTING.id.md

@@ -0,0 +1,323 @@
+# whisper-windows-mcp — Pemecahan Masalah
+
+---
+
+## Daftar Periksa Cepat
+
+Sebelum menyelidiki lebih dalam, verifikasi semua hal berikut:
+
+- Jalur di `claude_desktop_config.json` menggunakan **dua backslash** (`C:\\whisper\\...`)
+- `whisper-cli.exe` ada di jalur yang ditentukan dalam `WHISPER_CLI_PATH`
+- File model `.bin` ada di jalur yang ditentukan dalam `WHISPER_MODEL`
+- FFmpeg terpasang dan dapat diakses (`ffmpeg -version` berfungsi di command prompt)
+- Claude Desktop sudah **di-restart penuh** setelah mengedit konfigurasi (keluar dari system tray, bukan sekadar menutup jendela)
+- Server whisper menampilkan **berjalan** (lencana hijau) di Pengaturan → Pengembang
+
+---
+
+## "whisper tidak terhubung" atau tidak ada alat yang tersedia
+
+**Penyebab paling umum:** Claude Desktop tidak di-restart penuh setelah mengedit konfigurasi.
+
+1. Klik kanan ikon Claude di system tray → Keluar
+2. Buka kembali Claude Desktop
+3. Buka Pengaturan → Pengembang dan periksa lencana **berjalan** berwarna hijau di sebelah whisper
+
+Jika masih tidak muncul:
+
+1. Buka `claude_desktop_config.json` dan periksa kesalahan sintaks JSON (koma yang hilang, kurung kurawal yang tidak cocok)
+2. Pastikan semua jalur menggunakan dua backslash
+3. Jalankan `check_config` di Claude Desktop untuk mendapatkan diagnostik
+
+---
+
+## download_model timeout pada model besar
+
+Claude Desktop memiliki timeout 4 menit untuk panggilan alat MCP. Unduhan model besar pada koneksi lambat mungkin melebihi batas ini.
+
+**Ukuran file:**
+- `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
+
+Pada koneksi cepat (100 Mbps+), bahkan large-v3 selesai diunduh dalam waktu kurang dari 4 menit. Pada koneksi lebih lambat, gunakan browser atau PowerShell untuk mengunduh langsung dan tempatkan file di direktori model secara manual:
+
+```powershell
+# Contoh — unduh large-v3-turbo secara langsung
+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"
+```
+
+Kemudian gunakan `switch_model ggml-large-v3-turbo.bin` untuk mengaktifkannya.
+
+---
+
+## `check_config` melaporkan whisper-cli.exe tidak ditemukan
+
+Jalur di konfigurasi tidak cocok dengan lokasi file yang sebenarnya.
+
+Verifikasi file ada:
+```
+dir C:\whisper\Release\whisper-cli.exe
+```
+
+Jika ada di tempat lain, perbarui `WHISPER_CLI_PATH` di konfigurasi Anda agar sesuai dengan jalur yang sebenarnya.
+
+---
+
+## `check_config` melaporkan FFmpeg tidak ditemukan
+
+FFmpeg tidak terpasang atau tidak ada di PATH sistem Anda.
+
+Pasang via winget:
+```
+winget install ffmpeg
+```
+
+Atau unduh dari [ffmpeg.org](https://ffmpeg.org/download.html), ekstrak, dan tambahkan folder `bin` ke PATH sistem Anda.
+
+Setelah memasang, buka command prompt baru dan verifikasi:
+```
+ffmpeg -version
+```
+
+Jika Anda memasang FFmpeg ke lokasi non-standar, atur variabel lingkungan `FFMPEG_PATH` di konfigurasi Claude Desktop:
+```json
+"env": {
+  "FFMPEG_PATH": "C:\\ffmpeg\\bin\\ffmpeg.exe"
+}
+```
+
+---
+
+## Output transkripsi penuh dengan tag `[FOREIGN]`
+
+**Penyebab:** Anda menggunakan model khusus bahasa Inggris (misalnya `ggml-medium.en.bin`) pada audio non-Inggris. Model khusus bahasa Inggris tidak dapat memproses bahasa lain dan menghasilkan `[FOREIGN]` sebagai placeholder untuk setiap segmen yang tidak dapat ditangani.
+
+**Solusi:** Unduh dan gunakan `ggml-large-v3.bin` — model multibahasa. Ini diperlukan untuk transkripsi non-Inggris, deteksi bahasa otomatis, atau terjemahan.
+
+```
+https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3.bin
+```
+
+Simpan ke `C:\whisper\models\` dan perbarui konfigurasi:
+```json
+"WHISPER_MODEL": "C:\\whisper\\models\\ggml-large-v3.bin"
+```
+
+Atau ganti per-transkripsi menggunakan parameter `model` di `transcribe_audio` atau `generate_subtitles`.
+
+> **Catatan:** Model khusus bahasa Inggris (`*.en.bin`) lebih cepat dan akurat untuk konten bahasa Inggris tetapi sama sekali tidak dapat menangani bahasa lain. Jika Anda bekerja dengan konten multibahasa, `large-v3` adalah model yang tepat terlepas dari hardware.
+
+---
+
+## Transkripsi tidak menghasilkan output atau file kosong
+
+**Kemungkinan penyebab:**
+
+1. **Model salah untuk bahasa** — Model khusus bahasa Inggris (`*.en.bin`) tidak dapat mentranskrip bahasa lain. Gunakan `ggml-large-v3.bin` untuk konten multibahasa.
+
+2. **Kualitas audio terlalu rendah** — File dengan bitrate sangat rendah (misalnya rekaman ponsel `.3gp` lama menggunakan codec AMR-NB ~12kbps) mungkin berada di batas kemampuan whisper. Lingkungan yang bising (kebisingan latar belakang, gema, pembicara jauh) juga menantang. Coba `large-v3` yang lebih baik menangani audio yang terdegradasi.
+
+3. **File diam atau rusak** — Jalankan `analyze_media` pada file untuk memeriksa apakah FFprobe mendeteksi aliran audio yang valid.
+
+4. **Kegagalan konversi** — File mungkin tidak dikonversi ke WAV dengan benar. Coba konversi secara manual terlebih dahulu:
+```
+ffmpeg -i yourfile.3gp -ar 16000 -ac 1 output.wav
+```
+Kemudian transkripsi WAV secara langsung.
+
+---
+
+## Tugas latar belakang gagal pada file dengan karakter khusus atau Unicode di nama file
+
+**Penyebab:** whisper-cli.exe tidak dapat menulis file output saat jalur mengandung karakter Unicode (bahasa Indonesia, Jepang, Korea, emoji, tanda kurung, dll.) atau karakter khusus tertentu.
+
+**Solusi sementara saat ini:** Ubah nama file agar hanya menggunakan karakter ASCII sebelum transkripsi, lalu ubah nama kembali jika diperlukan.
+
+```
+ren "nama_file_indonesia.mp4" "temp_transcribe.mp4"
+```
+
+**Status:** Ini adalah bug yang diketahui. Perbaikan direncanakan yang akan merutekan output melalui jalur temp yang disanitasi dan memindahkan hasilnya ke tujuan yang benar setelah selesai.
+
+---
+
+## Tugas latar belakang menampilkan "gagal" tanpa output
+
+**Kemungkinan penyebab:**
+
+1. **Nama file Unicode** — Lihat di atas.
+
+2. **Jalur model salah** — Proses terpisah tidak mewarisi jalur yang telah dikoreksi. Jalankan `check_config` untuk memverifikasi jalur.
+
+3. **Proses dihentikan** — Jika whisper-cli.exe dihentikan secara manual di tengah tugas, tidak ada file output yang akan ada. Coba lagi.
+
+4. **VRAM tidak cukup** — Model besar pada GPU dengan VRAM rendah mungkin gagal secara diam-diam. Coba model yang lebih kecil.
+
+5. **Konversi file gagal** — Coba transkripsi file WAV langsung untuk mengisolasi apakah masalahnya ada di konversi atau transkripsi.
+
+---
+
+## Transkripsi latar belakang tidak menghasilkan output SRT
+
+**Penyebab:** Mode latar belakang (`background=true` di `transcribe_audio`) saat ini hanya menghasilkan output `.txt`. Format SRT dalam mode latar belakang belum diimplementasikan.
+
+**Solusi:** Untuk file di bawah ~4 menit, gunakan `generate_subtitles` dalam mode pemblokiran. Untuk file yang lebih panjang, transkripsi dalam mode latar belakang terlebih dahulu untuk mendapatkan `.txt`, kemudian jika SRT diperlukan, gunakan `generate_subtitles` pada file yang sama (akan mentranskrip ulang).
+
+**Status:** Dukungan SRT dalam mode latar belakang direncanakan untuk rilis mendatang.
+
+---
+
+## GPU tidak digunakan (CPU macet di atas 50%)
+
+**Penyebab:** Anda menjalankan binary khusus CPU yang disertakan dengan rilis whisper.cpp standar.
+
+**Solusi:** Unduh build yang mengaktifkan Vulkan dari [halaman rilis](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0) dan ekstrak ke `C:\whisper\Release\`.
+
+Verifikasi akselerasi GPU aktif:
+- Minta Claude `check_system`
+- Cari `✅ Vulkan binary: ggml-vulkan.dll found` dalam output
+- Pantau Task Manager → Performa → GPU selama transkripsi — utilisasi GPU seharusnya naik ke 15–30%
+
+---
+
+## `check_system` melaporkan jumlah VRAM yang salah
+
+Ini adalah keterbatasan Windows yang diketahui. Perintah `wmic` membaca VRAM dari registry, yang pada banyak kartu AMD melaporkan setengah VRAM fisik. Vega 56 dengan 8GB HBM2 biasanya menampilkan 4GB. Ini hanya masalah tampilan — whisper menggunakan VRAM fisik penuh selama inferensi.
+
+---
+
+## Error "Transkripsi sudah berlangsung"
+
+Ada proses `whisper-cli.exe` yang berjalan dari tugas sebelumnya. Tunggu hingga selesai, atau:
+
+1. Buka Task Manager → tab Detail
+2. Temukan `whisper-cli.exe`
+3. Klik kanan → Akhiri tugas
+
+Kemudian coba lagi.
+
+---
+
+## Deteksi bahasa otomatis salah
+
+Deteksi otomatis Whisper berjalan pada 30 detik pertama audio. Jika file dimulai dalam bahasa yang berbeda dari sebagian besar kontennya, deteksi mungkin salah.
+
+**Solusi:** Tentukan bahasa secara eksplisit (misalnya `language=id`) daripada mengandalkan deteksi otomatis.
+
+---
+
+## Pembuatan subtitle menghasilkan "(berbicara dalam bahasa asing)" di seluruh bagian
+
+Whisper mendeteksi ucapan tetapi tidak dapat mentranskrip. Penyebab paling umum:
+
+1. **Model salah** — Menggunakan model khusus bahasa Inggris pada audio non-Inggris. Gunakan `large-v3`.
+
+2. **Kualitas audio** — Lingkungan yang bising (dapur, kerumunan, gema) mungkin mengalahkan model medium. Coba `large-v3`.
+
+3. **Bahasa campuran** — File dengan dua bahasa yang bergantian akan membuat bahasa minoritas diisi placeholder dengan pengaturan satu bahasa.
+
+---
+
+## Terjemahan subtitle hanya menghasilkan bahasa Inggris
+
+Ini adalah desain yang disengaja. Flag `--translate` bawaan Whisper hanya menerjemahkan **ke bahasa Inggris**. Untuk terjemahan ke bahasa target lain, terjemahkan konten file `.srt` secara terpisah.
+
+---
+
+## Transkripsi batch berhenti maju
+
+Panggil `check_batch_progress` lagi. Jika masih macet:
+
+1. Periksa Task Manager untuk proses `whisper-cli.exe` yang berjalan
+2. Periksa log tugas di `%TEMP%\whisper-mcp-jobs\`
+3. File yang gagal ditandai dalam laporan batch — jalankan ulang secara individual dengan `transcribe_audio`
+
+---
+
+## Membersihkan direktori tugas sementara
+
+whisper-windows-mcp menulis file status tugas dan log ke `%TEMP%\whisper-mcp-jobs\` selama transkripsi. File-file ini terakumulasi dari waktu ke waktu dan dapat menghabiskan ruang disk, terutama file `.log` dari tugas transkripsi yang panjang.
+
+Setelah batch atau tugas selesai dan Anda telah memverifikasi transkrip output, Anda dapat dengan aman menghapus semua yang ada di direktori ini:
+
+```powershell
+Remove-Item "$env:TEMP\whisper-mcp-jobs\*" -Recurse -Force
+```
+
+Direktori akan dibuat ulang secara otomatis pada transkripsi berikutnya. Tidak ada file output transkrip yang disimpan secara permanen di sini — file dipindahkan ke direktori sumber saat selesai. Hanya metadata tugas dan log yang tersisa.
+
+**Catatan:** Jangan hapus direktori ini saat transkripsi sedang berlangsung — file status batch diperlukan agar `check_batch_progress` berfungsi.
+
+---
+
+## Batch besar tanpa pengawasan dari command line
+
+Untuk batch yang sangat besar di mana Anda ingin menjalankan semalaman tanpa Claude, gunakan PowerShell.
+
+**Penting:** whisper-cli.exe tidak dapat membaca MP4, MKV, atau sebagian besar format video secara langsung. FFmpeg harus mengkonversi setiap file ke WAV terlebih dahulu. whisper juga menulis transkrip ke stdout dan output diagnostik ke stderr — gunakan `Start-Process -RedirectStandardOutput` untuk menangkap transkrip dengan benar. Menggunakan pipe `|` atau mengalihkan stderr dengan `2>$null` tidak menangkap apa pun.
+
+```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."
+```
+
+Ganti `*.mp4` dengan `*.mkv`, `*.m4a`, dll. sesuai jenis file Anda. Pemeriksaan lewati `Test-Path` berarti menjalankan ulang skrip setelah gangguan tidak akan memproses ulang file yang sudah selesai.
+
+Script ini menulis file `.txt` di sebelah setiap sumber. Alat MCP akan mengenali file-file ini sebagai sudah ditranskripsi saat Anda menjalankan `analyze_media` atau `start_batch` setelahnya.
+
+---
+
+## Lokasi file konfigurasi
+
+```
+C:\Users\NamaPengguna\AppData\Roaming\Claude\claude_desktop_config.json
+```
+
+Jika `AppData` tidak terlihat: Tampilan → Tampilkan → Item tersembunyi di File Explorer.
+
+---
+
+## Contoh konfigurasi lengkap yang berfungsi
+
+```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` default ke `ffmpeg` (mengasumsikan ada di PATH). Atur secara eksplisit hanya jika FFmpeg dipasang di lokasi non-standar.