whisper-windows-mcp 2.3.0 → 2.5.0

package/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: build + test
+    runs-on: windows-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm test

package/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  release:
+    types: [created]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm install
+      - run: npm run build
+      - run: npm publish --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/PRIVACY.es.md

@@ -89,6 +89,8 @@ Cuando el modo de privacidad está activo, se muestra una divulgación de confir
 
 El texto de la divulgación es idéntico cada vez por diseño. La repetición es el punto: si estás manejando contenido sensible, debes confirmar explícitamente cada operación.
 
+La confirmación está vinculada a la **operación específica** — la herramienta junto con sus argumentos exactos. Confirmar una transcripción no puede satisfacer la barrera de una operación diferente, y cambiar cualquier parámetro se trata como una nueva operación que requiere su propia confirmación.
+
 Para `start_batch` con modo de privacidad: se requiere una confirmación antes de que el lote comience. Todos los archivos se procesan entonces de forma autónoma. No se devuelve texto de transcripción en ningún momento — solo metadatos de progreso del lote.
 
 ---

package/PRIVACY.id.md

@@ -89,6 +89,8 @@ Saat mode privasi aktif, konfirmasi pengungkapan ditampilkan **sebelum setiap op
 
 Teks pengungkapan identik setiap saat berdasarkan desain. Pengulangannya adalah intinya: jika Anda menangani konten sensitif, Anda harus mengkonfirmasi setiap operasi secara eksplisit.
 
+Konfirmasi terikat pada **operasi spesifik** — alat beserta argumen persisnya. Mengonfirmasi satu transkripsi tidak dapat memenuhi gerbang operasi yang berbeda, dan mengubah parameter apa pun diperlakukan sebagai operasi baru yang memerlukan konfirmasinya sendiri.
+
 Untuk `start_batch` dengan mode privasi: satu konfirmasi diperlukan sebelum batch dimulai. Semua file kemudian diproses tanpa pengawasan. Tidak ada teks transkrip yang dikembalikan pada titik mana pun — hanya metadata kemajuan batch.
 
 ---

package/PRIVACY.ja.md

@@ -89,6 +89,8 @@ per-callパラメーターはグローバル環境変数をどちらの方向に
 
 開示テキストは毎回同一です。これは意図的な設計です。機密性の高いコンテンツを扱う場合は、各操作を明示的に確認すべきです。
 
+確認は**特定の操作**（ツールとその正確な引数）に紐づけられています。ある文字起こしを確認しても、別の操作のゲートを満たすことはできません。また、いずれかのパラメータを変更すると、新しい操作として扱われ、独自の確認が必要になります。
+
 プライバシーモードでの`start_batch`：バッチ開始前に一度だけ確認が必要です。その後すべてのファイルは無人で処理されます。どの時点でもトランスクリプトテキストは返されません — バッチ進捗メタデータのみが返されます。
 
 ---

package/PRIVACY.ko.md

@@ -89,6 +89,8 @@ whisper-windows-mcp는 로컬 우선 아키텍처를 기반으로 구축되었
 
 공개 텍스트는 의도적으로 매번 동일합니다. 반복이 핵심입니다: 민감한 콘텐츠를 처리하는 경우 각 작업을 명시적으로 확인해야 합니다.
 
+확인은 **특정 작업**(도구와 그 정확한 인수)에 결합되어 있습니다. 한 전사를 확인해도 다른 작업의 게이트를 충족할 수 없으며, 매개변수를 하나라도 변경하면 자체 확인이 필요한 새 작업으로 취급됩니다.
+
 `start_batch`에서 개인 정보 모드 사용 시: 배치 시작 전에 확인 한 번이 필요합니다. 이후 모든 파일이 무인으로 처리됩니다. 어떤 시점에서도 전사 텍스트가 반환되지 않습니다 — 배치 진행 메타데이터만 반환됩니다.
 
 ---

package/PRIVACY.md

@@ -89,6 +89,8 @@ When privacy mode is active, a confirmation disclosure is shown **before every o
 
 The disclosure text is identical every time by design. The repetition is the point: if you are handling sensitive content, you should be confirming each operation explicitly.
 
+The confirmation is bound to the **specific operation** — the tool plus its exact arguments. Confirming one transcription cannot satisfy a different operation's gate, and changing any parameter is treated as a new operation requiring its own confirmation.
+
 For `start_batch` with privacy mode: one confirmation is required before the batch starts. All files then process unattended. No transcript text is returned at any point — only batch progress metadata.
 
 ---

package/PRIVACY.pl.md

@@ -89,6 +89,8 @@ Gdy tryb prywatności jest aktywny, potwierdzenie ujawnienia jest wyświetlane *
 
 Tekst ujawnienia jest identyczny za każdym razem z projektu. Powtórzenie jest istotą: jeśli obsługujesz wrażliwe treści, powinieneś jawnie potwierdzać każdą operację.
 
+Potwierdzenie jest powiązane z **konkretną operacją** — narzędziem wraz z jego dokładnymi argumentami. Potwierdzenie jednej transkrypcji nie może spełnić bramki innej operacji, a zmiana dowolnego parametru jest traktowana jako nowa operacja wymagająca własnego potwierdzenia.
+
 Dla `start_batch` z trybem prywatności: przed rozpoczęciem partii wymagane jest jedno potwierdzenie. Następnie wszystkie pliki są przetwarzane bez nadzoru. Tekst transkrypcji nie jest zwracany w żadnym momencie — tylko metadane postępu partii.
 
 ---

package/PRIVACY.pt-BR.md

@@ -89,6 +89,8 @@ Quando o modo de privacidade está ativo, uma confirmação de divulgação é e
 
 O texto da divulgação é idêntico a cada vez por design. A repetição é o ponto: se você está lidando com conteúdo sensível, você deve confirmar explicitamente cada operação.
 
+A confirmação está vinculada à **operação específica** — a ferramenta junto com seus argumentos exatos. Confirmar uma transcrição não pode satisfazer a barreira de uma operação diferente, e alterar qualquer parâmetro é tratado como uma nova operação que exige sua própria confirmação.
+
 Para `start_batch` com modo de privacidade: uma confirmação é necessária antes de o lote começar. Todos os arquivos são então processados sem supervisão. Nenhum texto de transcrição é retornado em nenhum momento — apenas metadados de progresso do lote.
 
 ---

package/PRIVACY.ro.md

@@ -89,6 +89,8 @@ Când modul de confidențialitate este activ, o dezvăluire de confirmare este a
 
 Textul dezvăluirii este identic de fiecare dată prin design. Repetiția este intenționată: dacă gestionezi conținut sensibil, ar trebui să confirmi explicit fiecare operațiune.
 
+Confirmarea este legată de **operațiunea specifică** — instrumentul împreună cu argumentele sale exacte. Confirmarea unei transcrieri nu poate satisface bariera unei alte operațiuni, iar modificarea oricărui parametru este tratată ca o operațiune nouă care necesită propria confirmare.
+
 Pentru `start_batch` cu modul de confidențialitate: o confirmare este necesară înainte de începerea lotului. Toate fișierele sunt apoi procesate nesupravegheate. Niciun text de transcriere nu este returnat în niciun moment — doar metadate de progres ale lotului.
 
 ---

package/PRIVACY.uk.md

@@ -89,6 +89,8 @@ whisper-windows-mcp побудовано на архітектурі з пріо
 
 Текст розкриття щоразу однаковий навмисно. Повторення — це і є суть: якщо ви працюєте з чутливим контентом, ви маєте явно підтверджувати кожну операцію.
 
+Підтвердження прив'язане до **конкретної операції** — інструмента разом із його точними аргументами. Підтвердження однієї транскрипції не може задовольнити бар'єр іншої операції, а зміна будь-якого параметра вважається новою операцією, яка потребує власного підтвердження.
+
 Для `start_batch` з режимом конфіденційності: перед початком пакету потрібне одне підтвердження. Далі всі файли опрацьовуються без нагляду. Текст транскрипції не повертається жодного разу — лише метадані прогресу пакету.
 
 ---

package/PRIVACY.vi.md

@@ -89,6 +89,8 @@ Khi chế độ quyền riêng tư đang hoạt động, một xác nhận công
 
 Văn bản công khai giống nhau mỗi lần theo thiết kế. Sự lặp lại mới là điểm mấu chốt: nếu bạn đang xử lý nội dung nhạy cảm, bạn phải xác nhận rõ ràng từng thao tác.
 
+Xác nhận được gắn với **thao tác cụ thể** — công cụ cùng với các đối số chính xác của nó. Việc xác nhận một phiên âm không thể thỏa mãn cổng kiểm soát của một thao tác khác, và việc thay đổi bất kỳ tham số nào đều được coi là một thao tác mới cần xác nhận riêng.
+
 Đối với `start_batch` với chế độ quyền riêng tư: cần một xác nhận trước khi đợt bắt đầu. Tất cả tệp sau đó được xử lý không giám sát. Không có văn bản phiên âm nào được trả về ở bất kỳ thời điểm nào — chỉ có siêu dữ liệu tiến trình đợt.
 
 ---

package/README.es.md

@@ -1,5 +1,9 @@
 # whisper-windows-mcp
 
+[![CI](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml)
+
+[![whisper-windows-mcp MCP server](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp/badges/card.svg)](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp)
+
 Servidor MCP (Model Context Protocol) nativo para Windows. Utiliza [whisper.cpp](https://github.com/ggml-org/whisper.cpp) para transcribir archivos de audio y video localmente en Claude Desktop — con aceleración por GPU, soporte multilingüe y procesamiento por lotes. Toda la transcripción se ejecuta localmente — ningún archivo de audio, video ni ruta de archivo se envía al exterior.
 
 > **¿Por qué existe este paquete?**
@@ -179,6 +183,7 @@ Transcribe un único archivo. Soporta modo de bloqueo (predeterminado) o en segu
 | `word_timestamps` | Una palabra por segmento con marca de tiempo. Útil para alineación de clips. |
 | `max_segment_length` | Longitud máxima de segmento en caracteres. |
 | `diarize` | Diarización de hablantes estéreo — requiere audio estéreo con hablantes en canales separados. |
+| `tinydiarize` | Detección de turnos de hablante en mono — marca `[SPEAKER_TURN]` en los cambios de hablante en audio de un solo canal. Requiere un modelo tdrz: `download_model small.en-tdrz`, luego `switch_model ggml-small.en-tdrz.bin`. |
 | `vad_model` | Ruta al archivo .bin del modelo Silero VAD. Elimina silencios antes de transcribir — reduce alucinaciones en archivos ruidosos. |
 | `offset_t` | Desplazamiento de inicio en milisegundos. |
 | `duration` | Duración a procesar desde el desplazamiento en milisegundos. |
@@ -294,6 +299,21 @@ Detecta el hardware GPU y confirma si la aceleración Vulkan está disponible. R
 
 ---
 
+### `whisper_server`
+Inicia, detiene o consulta el **servidor de modelo persistente** (el `whisper-server` de whisper.cpp). Mientras está en ejecución, el modelo activo permanece residente en la VRAM y cada llamada a `transcribe_audio` / `transcribe_batch` se atiende a través de localhost **sin recarga de modelo por archivo** — una gran mejora de velocidad al transcribir muchos archivos cortos, donde de otro modo el coste único de carga del modelo domina.
+
+| Parámetro | Descripción |
+|---|---|
+| `action` | `start` — arranca con el modelo activo residente; `stop` — apaga y libera la VRAM; `status` — reporta el estado de ejecución, el modelo residente, el puerto y el tiempo de actividad. |
+
+- ⚠️ **El modelo residente retiene la VRAM de la GPU durante toda la vida del servidor.** Inícialo deliberadamente, realiza tu trabajo y luego deténlo con `stop` para devolver la GPU a otras aplicaciones que compartan la tarjeta. Detenerlo realiza un cierre completo para que la VRAM se libere realmente.
+- Usar `switch_model` mientras el servidor está en ejecución intercambia en caliente el modelo residente en el sitio (sin reinicio).
+- Vinculado solo a `127.0.0.1` — nunca expuesto en la red.
+- Mientras el servidor está activo, las operaciones que necesitan la CLI de un solo uso — tareas en segundo plano, `start_batch`, `generate_subtitles`, salida `lrc`/`csv` y opciones avanzadas por llamada que la API HTTP no respeta (`beam_size`, `best_of`, `word_timestamps`, `diarize`, `tinydiarize`, `vad_model`, `offset_t`, `duration`) — son **rechazadas** con un mensaje de "detén el servidor primero" en lugar de ignorarse silenciosamente, de modo que ningún segundo motor compita jamás por la GPU.
+- Requiere `whisper-server.exe` (se distribuye junto a `whisper-cli.exe`). Configúralo con `WHISPER_SERVER_PATH` / `WHISPER_SERVER_PORT` si es necesario.
+
+---
+
 ## Formatos soportados
 
 | Tipo | Formatos |
@@ -364,7 +384,11 @@ Esta herramienta fue creada para minimizar las interacciones con la API de Claud
 | `WHISPER_CLI_PATH` | Ruta a whisper-cli.exe (obligatorio) |
 | `WHISPER_MODEL` | Ruta al archivo de modelo .bin (obligatorio) |
 | `WHISPER_THREADS` | Anula el número de hilos de CPU |
+| `WHISPER_GPU_DEVICE` | Índice del dispositivo Vulkan al que fijar la transcripción, para sistemas con múltiples GPU (el índice de enumeración de Vulkan — consulta el registro de inicio de whisper-cli; no el orden de GPU de Windows). Anulable por llamada con `gpu_device`. Ver [TROUBLESHOOTING.md](TROUBLESHOOTING.md). |
+| `WHISPER_FOREGROUND_MAX_SEC` | Límite de la transcripción en primer plano en segundos (predeterminado 210). Los archivos cuya ejecución se estima más larga se enrutan al modo en segundo plano en lugar de arriesgar el tiempo de espera de herramienta de ~4 minutos de Claude Desktop. |
 | `FFMPEG_PATH` | Ruta a ffmpeg si no está en el PATH del sistema |
+| `WHISPER_SERVER_PATH` | Ruta a `whisper-server.exe` para el servidor de modelo persistente (predeterminado: junto a `whisper-cli.exe`). Ver la herramienta `whisper_server`. |
+| `WHISPER_SERVER_PORT` | Puerto de localhost para el servidor de modelo persistente (predeterminado 8571). Siempre vinculado a `127.0.0.1`. |
 | `WHISPER_PRIVACY_MODE` | Establece en `true` para que todas las respuestas de herramientas devuelvan solo metadatos — ningún texto de transcripción devuelto a Claude. Para contenido regulado o confidencial. Puede anularse por llamada con el parámetro `privacy_mode`. Ver [PRIVACY.md](PRIVACY.md). |
 | `WHISPER_CONSENT_ACKNOWLEDGED` | Establece en `true` para omitir la divulgación de consentimiento única por sesión que se muestra antes de devolver texto de transcripción. Establécelo cuando entiendas los límites de privacidad y ya no necesites el recordatorio. Sin efecto cuando el modo de privacidad está activo. |
 
@@ -380,13 +404,15 @@ Get-FileHash "C:\whisper\Release\whisper-cli.exe" -Algorithm SHA256
 
 El hash esperado está documentado en la [página de releases](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0).
 
-**Validación de entrada.** Todas las rutas de archivo son validadas antes de su uso — las rutas UNC (`\\server\share`) y las secuencias de traversal de directorio (`..`) son rechazadas. Los archivos de más de 10 GB son rechazados para prevenir el agotamiento de recursos.
+**Validación de entrada.** Todas las rutas de archivo y de carpeta son validadas antes de su uso, en cada herramienta que acepta una — las rutas UNC (`\\server\share`) y las secuencias de traversal de directorio (`..`) son rechazadas. Los archivos de más de 10 GB son rechazados para prevenir el agotamiento de recursos. `job_id` y `batch_id` se comprueban contra el formato exacto emitido por el servidor antes de usarse para construir cualquier ruta de archivo, de modo que un ID manipulado no pueda salir del directorio de tareas.
+
+**Conciencia de inyección de transcripción.** Los archivos de audio pueden contener contenido hablado que, cuando se transcribe, se asemeja a instrucciones. Las defensas integradas de Claude manejan esto, pero vale la pena saber que el propio servidor MCP trata el contenido de transcripción como datos — nunca como instrucciones. Dado que el contenido transcrito aún puede influir en qué herramientas llama Claude a continuación, la validación de rutas/IDs se aplica de forma defensiva en lugar de confiar únicamente en la suposición de un solo usuario.
 
-**Conciencia de inyección de transcripción.** Los archivos de audio pueden contener contenido hablado que, cuando se transcribe, se asemeja a instrucciones. Las defensas integradas de Claude manejan esto, pero vale la pena saber que el propio servidor MCP trata el contenido de transcripción como datos — nunca como instrucciones.
+**Las descargas de modelos están restringidas.** La herramienta `download_model` solo descarga desde dos espacios de nombres de Hugging Face de confianza (`ggerganov/whisper.cpp` y `ggml-org`). Las URLs arbitrarias son rechazadas. Los redireccionamientos son validados contra una lista de permitidos antes de seguirlos. (Las descargas aún no se verifican contra un resumen SHA256 por modelo — ver SECURITY.md.)
 
-**Las descargas de modelos están restringidas.** La herramienta `download_model` solo descarga desde dos espacios de nombres de Hugging Face de confianza (`ggerganov/whisper.cpp` y `ggml-org`). Las URLs arbitrarias son rechazadas. Los redireccionamientos son validados contra una lista de permitidos antes de seguirlos.
+**La selección de modelos está en sandbox.** Tanto `switch_model` como la anulación `model` de `transcribe_audio` solo aceptan archivos `.bin` dentro del directorio de modelos configurado. Las rutas fuera de ese directorio son rechazadas mediante contención de rutas normalizada.
 
-**El cambio de modelos está en sandbox.** `switch_model` solo acepta archivos `.bin` dentro del directorio de modelos configurado. Las rutas fuera de ese directorio son rechazadas.
+**Sin shadowing de PATH.** Los binarios del sistema que el servidor invoca en tu nombre (`tasklist`, `wmic`) son llamados por ruta absoluta de `System32` para que no puedan ser suplantados por un ejecutable con el mismo nombre situado antes en el `PATH`.
 
 Ver [SECURITY.md](SECURITY.md) para la política de seguridad completa.
 

package/README.id.md

@@ -1,5 +1,9 @@
 # whisper-windows-mcp
 
+[![CI](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml)
+
+[![whisper-windows-mcp MCP server](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp/badges/card.svg)](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp)
+
 Server MCP (Model Context Protocol) khusus Windows. Menggunakan [whisper.cpp](https://github.com/ggml-org/whisper.cpp) untuk transkripsi file audio dan video secara lokal di Claude Desktop — dengan akselerasi GPU, dukungan multibahasa, dan pemrosesan batch. Semua transkripsi berjalan secara lokal — tidak ada file audio, video, maupun jalur file yang dikirim keluar.
 
 > **Mengapa paket ini ada?**
@@ -179,6 +183,7 @@ Transkripsi satu file. Mendukung mode pemblokiran (default) atau latar belakang
 | `word_timestamps` | Satu kata per segmen bertimestamp. Berguna untuk penyelarasan klip. |
 | `max_segment_length` | Panjang segmen maksimum dalam karakter. |
 | `diarize` | Diarisasi pembicara stereo — memerlukan audio stereo dengan pembicara di kanal terpisah. |
+| `tinydiarize` | Deteksi pergantian pembicara mono — menandai `[SPEAKER_TURN]` pada perubahan pembicara di audio satu kanal. Memerlukan model tdrz: `download_model small.en-tdrz`, lalu `switch_model ggml-small.en-tdrz.bin`. |
 | `vad_model` | Jalur ke file .bin model Silero VAD. Menghapus keheningan sebelum transkripsi — mengurangi halusinasi pada file yang bising. |
 | `offset_t` | Offset mulai dalam milidetik. |
 | `duration` | Durasi pemrosesan dalam milidetik dari offset. |
@@ -305,6 +310,21 @@ Deteksi hardware GPU dan konfirmasi akselerasi Vulkan tersedia. Melaporkan nama
 
 ---
 
+### `whisper_server`
+Jalankan, hentikan, atau periksa **server model persisten** (`whisper-server` milik whisper.cpp). Selama berjalan, model aktif tetap berada di VRAM dan setiap panggilan `transcribe_audio` / `transcribe_batch` dilayani melalui localhost dengan **tanpa pemuatan ulang model per file** — percepatan besar saat mentranskrip banyak file pendek, di mana biaya pemuatan model satu kali biasanya mendominasi.
+
+| Parameter | Deskripsi |
+|---|---|
+| `action` | `start` — luncurkan dengan model aktif tetap berada di memori; `stop` — matikan dan bebaskan VRAM; `status` — laporkan status berjalan, model yang berada di memori, port, dan uptime. |
+
+- ⚠️ **Model yang berada di memori menahan VRAM GPU selama seluruh masa hidup server.** Mulai secara sengaja, lakukan pekerjaan Anda, lalu `stop` untuk mengembalikan GPU ke aplikasi lain yang berbagi kartu tersebut. Menghentikan melakukan kill penuh sehingga VRAM benar-benar dibebaskan.
+- `switch_model` saat server berjalan melakukan hot-swap model yang berada di memori di tempat (tanpa restart).
+- Terikat hanya ke `127.0.0.1` — tidak pernah terekspos di jaringan.
+- Selama server aktif, operasi yang memerlukan CLI sekali-jalan — tugas latar belakang, `start_batch`, `generate_subtitles`, output `lrc`/`csv`, dan opsi per-panggilan lanjutan yang tidak didukung API HTTP (`beam_size`, `best_of`, `word_timestamps`, `diarize`, `tinydiarize`, `vad_model`, `offset_t`, `duration`) — akan **ditolak** dengan pesan "hentikan server terlebih dahulu" alih-alih diabaikan secara diam-diam, sehingga tidak ada mesin kedua yang pernah bersaing untuk GPU.
+- Memerlukan `whisper-server.exe` (dikirim bersama `whisper-cli.exe`). Konfigurasikan dengan `WHISPER_SERVER_PATH` / `WHISPER_SERVER_PORT` jika diperlukan.
+
+---
+
 ## Format yang Didukung
 
 | Tipe | Format |
@@ -375,7 +395,11 @@ Alat ini dibangun untuk meminimalkan interaksi Claude API. Seluruh alur kerja tr
 | `WHISPER_CLI_PATH` | Jalur ke whisper-cli.exe (wajib) |
 | `WHISPER_MODEL` | Jalur ke file model .bin (wajib) |
 | `WHISPER_THREADS` | Override jumlah thread CPU |
+| `WHISPER_GPU_DEVICE` | Indeks perangkat Vulkan untuk menyematkan transkripsi, untuk sistem multi-GPU (indeks enumerasi Vulkan — periksa log startup whisper-cli; bukan urutan GPU Windows). Dapat di-override per-panggilan dengan `gpu_device`. Lihat [TROUBLESHOOTING.md](TROUBLESHOOTING.md). |
+| `WHISPER_FOREGROUND_MAX_SEC` | Batas transkripsi latar depan dalam detik (default 210). File yang diperkirakan berjalan lebih lama dirutekan ke mode latar belakang alih-alih mempertaruhkan batas waktu alat ~4 menit milik Claude Desktop. |
 | `FFMPEG_PATH` | Jalur ke ffmpeg jika tidak ada di PATH sistem |
+| `WHISPER_SERVER_PATH` | Jalur ke `whisper-server.exe` untuk server model persisten (default: bersama `whisper-cli.exe`). Lihat alat `whisper_server`. |
+| `WHISPER_SERVER_PORT` | Port localhost untuk server model persisten (default 8571). Selalu terikat ke `127.0.0.1`. |
 | `WHISPER_PRIVACY_MODE` | Saat `true`, semua respons alat hanya mengembalikan metadata — tidak ada teks transkrip yang dikirimkan ke API Claude. Untuk konten yang diatur atau rahasia. Dapat di-override per-panggilan dengan parameter `privacy_mode`. Lihat [PRIVACY.md](PRIVACY.md). |
 | `WHISPER_CONSENT_ACKNOWLEDGED` | Saat `true`, melewati pengungkapan persetujuan sesi satu kali yang ditampilkan sebelum teks transkrip dikembalikan. Atur setelah Anda memahami batas privasi dan tidak lagi membutuhkan pengingat. Tidak berpengaruh saat mode privasi aktif. |
 
@@ -391,13 +415,15 @@ Get-FileHash "C:\whisper\Release\whisper-cli.exe" -Algorithm SHA256
 
 Hash yang diharapkan untuk binary rilis v1.4.0 didokumentasikan di [halaman rilis](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0).
 
-**Validasi input.** Semua jalur file divalidasi sebelum digunakan — jalur UNC (`\\server\share`) dan urutan traversal direktori (`..`) ditolak. File di atas 10 GB ditolak untuk mencegah kelelahan sumber daya.
+**Validasi input.** Semua jalur file dan folder divalidasi sebelum digunakan, pada setiap alat yang menerimanya — jalur UNC (`\\server\share`) dan urutan traversal direktori (`..`) ditolak. File di atas 10 GB ditolak untuk mencegah kelelahan sumber daya. `job_id` dan `batch_id` diperiksa terhadap format persis yang dibuat server sebelum digunakan untuk membangun jalur file apa pun, sehingga ID yang direkayasa tidak dapat keluar dari direktori tugas melalui traversal.
+
+**Kesadaran injeksi transkrip.** File audio dapat berisi konten yang diucapkan yang, saat ditranskripsi, menyerupai instruksi. Pertahanan bawaan Claude menangani ini, tetapi perlu diketahui bahwa konten transkrip diperlakukan sebagai data — tidak pernah sebagai instruksi — oleh server MCP itu sendiri. Karena konten yang ditranskripsi tetap dapat memengaruhi alat mana yang dipanggil Claude berikutnya, validasi jalur/ID diterapkan secara defensif alih-alih hanya mengandalkan asumsi pengguna tunggal.
 
-**Kesadaran injeksi transkrip.** File audio dapat berisi konten yang diucapkan yang, saat ditranskripsi, menyerupai instruksi. Pertahanan bawaan Claude menangani ini, tetapi perlu diketahui bahwa konten transkrip diperlakukan sebagai data — tidak pernah sebagai instruksi — oleh server MCP itu sendiri.
+**Unduhan model dibatasi.** Alat `download_model` hanya mengunduh dari dua namespace Hugging Face yang terpercaya (`ggerganov/whisper.cpp` dan `ggml-org`). URL sembarang ditolak. Pengalihan divalidasi terhadap daftar izin sebelum diikuti. (Unduhan belum diverifikasi terhadap digest SHA256 per-model — lihat SECURITY.md.)
 
-**Unduhan model dibatasi.** Alat `download_model` hanya mengunduh dari dua namespace Hugging Face yang terpercaya (`ggerganov/whisper.cpp` dan `ggml-org`). URL sembarang ditolak. Pengalihan divalidasi terhadap daftar izin sebelum diikuti.
+**Pemilihan model di-sandbox.** Baik `switch_model` maupun override `model` pada `transcribe_audio` hanya menerima file `.bin` dalam direktori model yang dikonfigurasi. Jalur di luar direktori tersebut ditolak melalui penahanan jalur yang dinormalisasi.
 
-**Penggantian model di-sandbox.** `switch_model` hanya menerima file `.bin` dalam direktori model yang dikonfigurasi. Jalur di luar direktori tersebut ditolak.
+**Tidak ada PATH shadowing.** Binary sistem yang dipanggil server atas nama Anda (`tasklist`, `wmic`) dipanggil melalui jalur absolut `System32` sehingga tidak dapat dibayangi oleh executable bernama sama yang berada lebih awal di `PATH`.
 
 Lihat [SECURITY.md](SECURITY.md) untuk kebijakan keamanan lengkap.
 

package/README.ja.md

@@ -1,5 +1,9 @@
 # whisper-windows-mcp
 
+[![CI](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml)
+
+[![whisper-windows-mcp MCP server](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp/badges/card.svg)](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp)
+
 Windows向けのネイティブMCP（Model Context Protocol）サーバーです。[whisper.cpp](https://github.com/ggml-org/whisper.cpp)を使用して、Claude Desktopで音声・動画ファイルをローカルに文字起こしできます。GPU加速、多言語対応、バッチ処理に対応しています。すべての文字起こし処理はローカルで実行 — 音声・動画ファイルやファイルパスが外部に送信されることは一切ありません。
 
 > **なぜこのパッケージが存在するのか？**
@@ -179,6 +183,7 @@ GPUが検出されVulkan加速が有効になっていることを確認しま
 | `word_timestamps` | タイムスタンプ付き1単語ごとのセグメント出力。クリップ位置合わせに有用。 |
 | `max_segment_length` | セグメントの最大文字数。 |
 | `diarize` | ステレオ話者識別 — 別々のチャンネルに話者が録音されたステレオ音声が必要。 |
+| `tinydiarize` | モノラルの話者交代検出 — 単一チャンネル音声で話者が変わる箇所に`[SPEAKER_TURN]`を付与します。tdrzモデルが必要：`download_model small.en-tdrz`を実行後、`switch_model ggml-small.en-tdrz.bin`。 |
 | `vad_model` | Silero VADモデル.binへのパス。文字起こし前に無音を除去 — ノイズの多いファイルでのハルシネーションを軽減。 |
 | `offset_t` | 開始オフセット（ミリ秒）。 |
 | `duration` | オフセットからの処理時間（ミリ秒）。 |
@@ -305,6 +310,21 @@ GPUハードウェアを検出しVulkan加速が利用可能か確認します
 
 ---
 
+### `whisper_server`
+**永続モデルサーバー**（whisper.cppの`whisper-server`）を起動、停止、または状態確認します。実行中はアクティブモデルがVRAMに常駐し、すべての`transcribe_audio` / `transcribe_batch`呼び出しがlocalhost経由で処理され、**ファイルごとのモデル再読み込みが発生しません** — 多数の短いファイルを文字起こしする際に大きな高速化となります。この場合、一度きりのモデル読み込みコストが支配的だからです。
+
+| パラメータ | 説明 |
+|---|---|
+| `action` | `start` — アクティブモデルを常駐させて起動；`stop` — 停止してVRAMを解放；`status` — 実行状態、常駐モデル、ポート、稼働時間を報告。 |
+
+- ⚠️ **常駐モデルはサーバーの生存期間中ずっとGPU VRAMを占有します。** 意図的に起動し、作業を行い、その後`stop`してカードを共有する他のアプリケーションにGPUを返してください。停止時は完全なkillを実行するため、VRAMが実際に解放されます。
+- サーバー実行中に`switch_model`を行うと、常駐モデルをその場でホットスワップします（再起動なし）。
+- `127.0.0.1`のみにバインドされます — ネットワークに公開されることは一切ありません。
+- サーバー起動中は、ワンショットCLIを必要とする操作 — バックグラウンドジョブ、`start_batch`、`generate_subtitles`、`lrc`/`csv`出力、およびHTTP APIが受け付けない高度なper-call オプション（`beam_size`、`best_of`、`word_timestamps`、`diarize`、`tinydiarize`、`vad_model`、`offset_t`、`duration`）— は、サイレントに無視されるのではなく「まずサーバーを停止してください」というメッセージとともに**拒否**されます。これにより2つ目のエンジンがGPUを奪い合うことは決してありません。
+- `whisper-server.exe`が必要です（`whisper-cli.exe`と一緒に同梱されています）。必要に応じて`WHISPER_SERVER_PATH` / `WHISPER_SERVER_PORT`で設定してください。
+
+---
+
 ## 対応フォーマット
 
 | 種類 | フォーマット |
@@ -375,7 +395,11 @@ whisper-windows-mcpには機密および規制対象コンテンツ向けの組
 | `WHISPER_CLI_PATH` | whisper-cli.exeへのパス（必須） |
 | `WHISPER_MODEL` | モデル.binファイルへのパス（必須） |
 | `WHISPER_THREADS` | CPUスレッド数の上書き |
+| `WHISPER_GPU_DEVICE` | マルチGPUシステムで文字起こしを固定するVulkanデバイスのインデックス（VulkanのenumerationインデックスでありWindowsのGPU順序ではありません — whisper-cliの起動ログを確認してください）。per-callで`gpu_device`により上書き可能。[TROUBLESHOOTING.md](TROUBLESHOOTING.md)を参照。 |
+| `WHISPER_FOREGROUND_MAX_SEC` | フォアグラウンド文字起こしの上限秒数（デフォルト210）。これより長く実行されると推定されるファイルは、Claude Desktopの約4分のツールタイムアウトのリスクを冒す代わりにバックグラウンドモードにルーティングされます。 |
 | `FFMPEG_PATH` | ffmpegがシステムPATHにない場合のパス |
+| `WHISPER_SERVER_PATH` | 永続モデルサーバー用の`whisper-server.exe`へのパス（デフォルト：`whisper-cli.exe`と同じ場所）。`whisper_server`ツールを参照。 |
+| `WHISPER_SERVER_PORT` | 永続モデルサーバーのlocalhostポート（デフォルト8571）。常に`127.0.0.1`にバインドされます。 |
 | `WHISPER_PRIVACY_MODE` | `true`の場合、すべてのツールレスポンスはメタデータのみを返し、トランスクリプトテキストはClaudeのAPIに送信されません。規制対象または機密性の高いコンテンツに使用します。per-callで`privacy_mode`パラメータを使用して上書き可能。[PRIVACY.md](PRIVACY.md)を参照。 |
 | `WHISPER_CONSENT_ACKNOWLEDGED` | `true`の場合、トランスクリプトテキストが返される前の一回限りのセッション同意開示をスキップします。プライバシーの境界を理解し、リマインダーが不要になったら設定してください。プライバシーモードが有効な場合には効果がありません。 |
 
@@ -391,13 +415,15 @@ Get-FileHash "C:\whisper\Release\whisper-cli.exe" -Algorithm SHA256
 
 v1.4.0リリースバイナリの期待されるハッシュは[リリースページ](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0)に記載されています。
 
-**入力検証。** すべてのファイルパスは使用前に検証されます — UNCパス（`\\server\share`）とディレクトリトラバーサル（`..`）は拒否されます。10GBを超えるファイルはリソース枯渇を防ぐために拒否されます。
+**入力検証。** すべてのファイルパスとフォルダパスは、それらを受け取るすべてのツールで使用前に検証されます — UNCパス（`\\server\share`）とディレクトリトラバーサル（`..`）は拒否されます。10GBを超えるファイルはリソース枯渇を防ぐために拒否されます。`job_id`と`batch_id`は、いかなるファイルパスの構築に使用される前にも、サーバーが生成する正確な形式と照合されるため、細工されたIDでjobsディレクトリの外へトラバースすることはできません。
+
+**トランスクリプトインジェクション対応。** 音声ファイルには、文字起こし時に指示のように見える内容が含まれる場合があります。Claudeの組み込み防御がこれを処理しますが、MCPサーバー自体はトランスクリプトの内容をデータとして扱い、指示として解釈しないことを知っておく価値があります。文字起こしされた内容がClaudeが次にどのツールを呼び出すかに影響を与える可能性があるため、シングルユーザーの前提のみに頼るのではなく、パス/ID検証を防御的に適用しています。
 
-**トランスクリプトインジェクション対応。** 音声ファイルには、文字起こし時に指示のように見える内容が含まれる場合があります。Claudeの組み込み防御がこれを処理しますが、MCPサーバー自体はトランスクリプトの内容をデータとして扱い、指示として解釈しないことを知っておく価値があります。
+**モデルダウンロードの制限。** `download_model`ツールは信頼された2つのHugging Faceネームスペース（`ggerganov/whisper.cpp`と`ggml-org`）からのみダウンロードします。任意のURLは拒否されます。リダイレクトはフォロー前にアローリストで検証されます。（ダウンロードはまだモデルごとのSHA256ダイジェストで検証されていません — SECURITY.mdを参照。）
 
-**モデルダウンロードの制限。** `download_model`ツールは信頼された2つのHugging Faceネームスペース（`ggerganov/whisper.cpp`と`ggml-org`）からのみダウンロードします。任意のURLは拒否されます。リダイレクトはフォロー前にアローリストで検証されます。
+**モデル選択のサンドボックス化。** `switch_model`と`transcribe_audio`の`model`上書きの両方は、設定済みモデルディレクトリ内の`.bin`ファイルのみを受け付けます。そのディレクトリ外のパスは、正規化されたパス封じ込めによって拒否されます。
 
-**モデル切り替えのサンドボックス化。** `switch_model`は設定済みモデルディレクトリ内の`.bin`ファイルのみ受け付けます。そのディレクトリ外のパスは拒否されます。
+**PATHシャドウイングなし。** サーバーがユーザーに代わって呼び出すシステムバイナリ（`tasklist`、`wmic`）は、絶対`System32`パスで呼び出されるため、`PATH`上でより早い位置にある同名の実行ファイルによってシャドウイングされることはありません。
 
 完全なセキュリティポリシーについては[SECURITY.md](SECURITY.md)を参照してください。
 

package/README.ko.md

@@ -1,5 +1,9 @@
 # whisper-windows-mcp
 
+[![CI](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml)
+
+[![whisper-windows-mcp MCP server](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp/badges/card.svg)](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp)
+
 Windows 전용 네이티브 MCP(Model Context Protocol) 서버입니다. [whisper.cpp](https://github.com/ggml-org/whisper.cpp)를 사용하여 Claude Desktop에서 음성 및 동영상 파일을 로컬로 전사합니다. GPU 가속, 다국어 지원, 배치 처리를 지원합니다. 모든 전사 처리는 로컬에서 실행 — 음성, 동영상 파일이나 파일 경로가 외부로 전송되는 일은 없습니다.
 
 > **왜 이 패키지가 존재하는가?**
@@ -179,6 +183,7 @@ GPU가 감지되고 Vulkan 가속이 활성화되었는지 확인합니다.
 | `word_timestamps` | 타임스탬프가 있는 단어별 세그먼트. 클립 정렬에 유용. |
 | `max_segment_length` | 세그먼트 최대 문자 수. |
 | `diarize` | 스테레오 화자 분리 — 별도 채널에 화자가 녹음된 스테레오 음성 필요. |
+| `tinydiarize` | 모노 화자 전환 감지 — 단일 채널 음성에서 화자가 바뀌는 지점에 `[SPEAKER_TURN]`을 표시합니다. tdrz 모델이 필요합니다: `download_model small.en-tdrz`를 실행한 뒤 `switch_model ggml-small.en-tdrz.bin`. |
 | `vad_model` | Silero VAD 모델 .bin 경로. 전사 전 무음 제거 — 잡음이 많은 파일의 환각 감소. |
 | `offset_t` | 시작 오프셋(밀리초). |
 | `duration` | 오프셋부터 처리할 시간(밀리초). |
@@ -294,6 +299,21 @@ GPU 하드웨어를 감지하고 Vulkan 가속 사용 가능 여부를 확인합
 
 ---
 
+### `whisper_server`
+**영구 모델 서버**(whisper.cpp의 `whisper-server`)를 시작, 중지 또는 확인합니다. 실행 중에는 활성 모델이 VRAM에 상주하며 모든 `transcribe_audio` / `transcribe_batch` 호출이 localhost를 통해 처리됩니다 — **파일별 모델 재로드 없이** — 일회성 모델 로드 비용이 지배적인 짧은 파일을 많이 전사할 때 큰 속도 향상을 제공합니다.
+
+| 파라미터 | 설명 |
+|---|---|
+| `action` | `start` — 활성 모델을 상주시켜 실행; `stop` — 종료하고 VRAM 해제; `status` — 실행 상태, 상주 모델, 포트, 가동 시간 보고. |
+
+- ⚠️ **상주 모델은 서버의 전체 수명 동안 GPU VRAM을 점유합니다.** 의도적으로 시작하고, 작업을 수행한 뒤, `stop`으로 카드를 공유하는 다른 애플리케이션에 GPU를 반환하세요. 중지는 완전한 종료를 수행하므로 VRAM이 실제로 해제됩니다.
+- 서버가 실행 중일 때 `switch_model`은 상주 모델을 그 자리에서 핫스왑합니다(재시작 없음).
+- `127.0.0.1`에만 바인딩됩니다 — 네트워크에 노출되지 않습니다.
+- 서버가 실행 중인 동안, 일회성 CLI가 필요한 작업 — 백그라운드 작업, `start_batch`, `generate_subtitles`, `lrc`/`csv` 출력, 그리고 HTTP API가 준수하지 않는 고급 호출별 옵션(`beam_size`, `best_of`, `word_timestamps`, `diarize`, `tinydiarize`, `vad_model`, `offset_t`, `duration`) — 은 조용히 무시되는 대신 "먼저 서버를 중지하세요" 메시지와 함께 **거부**되므로, 두 번째 엔진이 GPU를 두고 경합하는 일이 절대 없습니다.
+- `whisper-server.exe`가 필요합니다(`whisper-cli.exe`와 함께 제공됨). 필요한 경우 `WHISPER_SERVER_PATH` / `WHISPER_SERVER_PORT`로 설정하세요.
+
+---
+
 ## 지원 포맷
 
 | 유형 | 포맷 |
@@ -364,7 +384,11 @@ whisper-windows-mcp에는 민감하고 규제 대상인 콘텐츠를 위한 내
 | `WHISPER_CLI_PATH` | whisper-cli.exe 경로 (필수) |
 | `WHISPER_MODEL` | 모델 .bin 파일 경로 (필수) |
 | `WHISPER_THREADS` | CPU 스레드 수 재정의 |
+| `WHISPER_GPU_DEVICE` | 다중 GPU 시스템에서 전사를 고정할 Vulkan 장치 인덱스(Windows GPU 순서가 아닌 Vulkan 열거 인덱스 — whisper-cli 시작 로그를 확인하세요). 호출별 `gpu_device`로 재정의 가능합니다. [TROUBLESHOOTING.md](TROUBLESHOOTING.md) 참고. |
+| `WHISPER_FOREGROUND_MAX_SEC` | 포그라운드 전사 한도(초, 기본값 210). 더 오래 실행될 것으로 추정되는 파일은 Claude Desktop의 약 4분 도구 타임아웃 위험을 감수하는 대신 백그라운드 모드로 라우팅됩니다. |
 | `FFMPEG_PATH` | ffmpeg가 시스템 PATH에 없을 경우 경로 |
+| `WHISPER_SERVER_PATH` | 영구 모델 서버용 `whisper-server.exe` 경로 (기본값: `whisper-cli.exe`와 동일 위치). `whisper_server` 도구 참고. |
+| `WHISPER_SERVER_PORT` | 영구 모델 서버의 localhost 포트 (기본값 8571). 항상 `127.0.0.1`에 바인딩됩니다. |
 | `WHISPER_PRIVACY_MODE` | `true`로 설정하면 모든 도구 응답에서 전사 텍스트 없이 메타데이터만 반환됩니다. 규제 대상 또는 기밀 콘텐츠에 사용합니다. 호출별 `privacy_mode` 파라미터로 재정의 가능합니다. [PRIVACY.md](PRIVACY.md) 참고. |
 | `WHISPER_CONSENT_ACKNOWLEDGED` | `true`로 설정하면 전사 텍스트 반환 전 표시되는 일회성 세션 동의 공개를 건너뜁니다. 개인 정보 경계를 이해하고 더 이상 알림이 필요하지 않을 때 설정하세요. 개인 정보 모드가 활성화된 경우 효과 없음. |
 
@@ -380,13 +404,15 @@ Get-FileHash "C:\whisper\Release\whisper-cli.exe" -Algorithm SHA256
 
 예상 해시는 [릴리스 페이지](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0)에 문서화되어 있습니다.
 
-**입력 검증.** 모든 파일 경로는 사용 전에 검증됩니다 — UNC 경로(`\\server\share`) 및 디렉터리 탐색 시퀀스(`..`)는 거부됩니다. 10 GB를 초과하는 파일은 리소스 고갈을 방지하기 위해 거부됩니다.
+**입력 검증.** 모든 파일 및 폴더 경로는 경로를 받는 모든 도구에서 사용 전에 검증됩니다 — UNC 경로(`\\server\share`) 및 디렉터리 탐색 시퀀스(`..`)는 거부됩니다. 10 GB를 초과하는 파일은 리소스 고갈을 방지하기 위해 거부됩니다. `job_id`와 `batch_id`는 파일 경로를 구성하는 데 사용되기 전에 서버가 발급한 정확한 형식과 대조되어, 조작된 ID가 작업 디렉터리 밖으로 탈출할 수 없습니다.
+
+**전사 인젝션 인식.** 음성 파일에는 전사 시 지시처럼 보이는 발화 내용이 포함될 수 있습니다. Claude의 내장 방어 기능이 이를 처리하지만, MCP 서버 자체도 전사 내용을 데이터로만 처리하며 지시로 해석하지 않는다는 점을 알아두는 것이 좋습니다. 전사된 내용이 Claude가 다음에 호출할 도구에 여전히 영향을 줄 수 있으므로, 경로/ID 검증은 단일 사용자 가정에만 의존하지 않고 방어적으로 적용됩니다.
 
-**전사 인젝션 인식.** 음성 파일에는 전사 시 지시처럼 보이는 발화 내용이 포함될 수 있습니다. Claude의 내장 방어 기능이 이를 처리하지만, MCP 서버 자체도 전사 내용을 데이터로만 처리하며 지시로 해석하지 않는다는 점을 알아두는 것이 좋습니다.
+**모델 다운로드는 제한됩니다.** `download_model` 도구는 두 개의 신뢰할 수 있는 Hugging Face 네임스페이스(`ggerganov/whisper.cpp` 및 `ggml-org`)에서만 다운로드합니다. 임의의 URL은 거부됩니다. 리다이렉트는 따르기 전에 허용 목록에 대해 검증됩니다. (다운로드는 아직 모델별 SHA256 다이제스트로 검증되지 않습니다 — SECURITY.md 참고.)
 
-**모델 다운로드는 제한됩니다.** `download_model` 도구는 두 개의 신뢰할 수 있는 Hugging Face 네임스페이스(`ggerganov/whisper.cpp` 및 `ggml-org`)에서만 다운로드합니다. 임의의 URL은 거부됩니다. 리다이렉트는 허용 목록에 대해 검증된 후 따릅니다.
+**모델 선택은 샌드박스화됩니다.** `switch_model`과 `transcribe_audio`의 `model` 재정의는 모두 설정된 모델 디렉터리 내의 `.bin` 파일만 허용합니다. 해당 디렉터리 외부의 경로는 정규화된 경로 격리를 통해 거부됩니다.
 
-**모델 전환은 샌드박스화됩니다.** `switch_model`은 설정된 모델 디렉터리 내의 `.bin` 파일만 허용합니다. 해당 디렉터리 외부의 경로는 거부됩니다.
+**PATH 섀도잉 없음.** 서버가 사용자를 대신하여 호출하는 시스템 바이너리(`tasklist`, `wmic`)는 절대 `System32` 경로로 호출되므로 `PATH`상 앞에 위치한 동일 이름의 실행 파일로 섀도잉될 수 없습니다.
 
 전체 보안 정책은 [SECURITY.md](SECURITY.md)를 참고하세요.
 

package/README.md

@@ -1,5 +1,9 @@
 # whisper-windows-mcp
 
+[![CI](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/eviscerations/whisper-windows-mcp/actions/workflows/ci.yml)
+
+[![whisper-windows-mcp MCP server](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp/badges/card.svg)](https://glama.ai/mcp/servers/eviscerations/whisper-windows-mcp)
+
 A Windows-native MCP (Model Context Protocol) server that lets Claude Desktop transcribe audio and video files locally using [whisper.cpp](https://github.com/ggml-org/whisper.cpp) — with GPU acceleration, multilingual support, and batch processing. All transcription runs locally — no audio, video, or file paths ever leave your machine.
 
 > **Why does this exist?**
@@ -179,6 +183,7 @@ Transcribe a single file. Supports blocking (default) or background mode for lon
 | `word_timestamps` | One word per timestamped segment. Useful for clip alignment. |
 | `max_segment_length` | Max segment length in characters. |
 | `diarize` | Stereo speaker diarization — requires stereo audio with speakers on separate channels. |
+| `tinydiarize` | Mono speaker-turn detection — marks `[SPEAKER_TURN]` at speaker changes on single-channel audio. Requires a tdrz model: `download_model small.en-tdrz`, then `switch_model ggml-small.en-tdrz.bin`. |
 | `vad_model` | Path to Silero VAD model .bin. Strips silence before transcription — reduces hallucinations on noisy files. |
 | `offset_t` | Start offset in milliseconds. |
 | `duration` | Process duration in milliseconds from offset. |
@@ -305,6 +310,21 @@ Detect GPU hardware and verify Vulkan acceleration is available. Reports GPU nam
 
 ---
 
+### `whisper_server`
+Start, stop, or check the **persistent model server** (whisper.cpp's `whisper-server`). While running, the active model stays resident in VRAM and every `transcribe_audio` / `transcribe_batch` call is served over localhost with **no per-file model reload** — a large speedup when transcribing many short files, where the one-time model-load cost otherwise dominates.
+
+| Parameter | Description |
+|---|---|
+| `action` | `start` — launch with the active model resident; `stop` — shut down and free VRAM; `status` — report running state, resident model, port, and uptime. |
+
+- ⚠️ **The resident model holds GPU VRAM for the server's whole lifetime.** Start it deliberately, do your work, then `stop` it to hand the GPU back to other applications sharing the card. Stopping performs a full kill so VRAM is actually released.
+- `switch_model` while the server is running hot-swaps the resident model in place (no restart).
+- Bound to `127.0.0.1` only — never exposed on the network.
+- While the server is up, operations that need the one-shot CLI — background jobs, `start_batch`, `generate_subtitles`, `lrc`/`csv` output, and advanced per-call options the HTTP API doesn't honor (`beam_size`, `best_of`, `word_timestamps`, `diarize`, `tinydiarize`, `vad_model`, `offset_t`, `duration`) — are **refused** with a "stop the server first" message rather than silently ignored, so no second engine ever contends for the GPU.
+- Requires `whisper-server.exe` (ships alongside `whisper-cli.exe`). Configure with `WHISPER_SERVER_PATH` / `WHISPER_SERVER_PORT` if needed.
+
+---
+
 ## Supported formats
 
 | Type | Formats |
@@ -375,7 +395,11 @@ This tool is built to minimize Claude API interactions. The entire transcription
 | `WHISPER_CLI_PATH` | Path to whisper-cli.exe (required) |
 | `WHISPER_MODEL` | Path to model .bin file (required) |
 | `WHISPER_THREADS` | CPU thread count override |
+| `WHISPER_GPU_DEVICE` | Vulkan device index to pin transcription to, for multi-GPU systems (the Vulkan enumeration index — check whisper-cli's startup log; not the Windows GPU order). Overridable per-call with `gpu_device`. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md). |
+| `WHISPER_FOREGROUND_MAX_SEC` | Foreground-transcription cutoff in seconds (default 210). Files estimated to run longer are routed to background mode instead of risking Claude Desktop's ~4-minute tool timeout. |
 | `FFMPEG_PATH` | Path to ffmpeg if not in system PATH |
+| `WHISPER_SERVER_PATH` | Path to `whisper-server.exe` for the persistent model server (default: alongside `whisper-cli.exe`). See the `whisper_server` tool. |
+| `WHISPER_SERVER_PORT` | Localhost port for the persistent model server (default 8571). Always bound to `127.0.0.1`. |
 | `WHISPER_PRIVACY_MODE` | When `true`, all tool responses return metadata only — no transcript text transmitted to Claude's API. For regulated or confidential content. Can be overridden per-call with the `privacy_mode` parameter. See [PRIVACY.md](PRIVACY.md). |
 | `WHISPER_CONSENT_ACKNOWLEDGED` | When `true`, skips the one-time session consent disclosure shown before transcript text is returned. Set after you understand the privacy boundary and no longer need the reminder. Has no effect when privacy mode is active. |
 
@@ -391,13 +415,15 @@ Get-FileHash "C:\whisper\Release\whisper-cli.exe" -Algorithm SHA256
 
 The expected hash for the v1.4.0 release binary is documented in the [releases page](https://github.com/eviscerations/whisper-windows-mcp/releases/tag/v1.4.0).
 
-**Input validation.** All file paths are validated before use — UNC paths (`\\server\share`) and directory traversal sequences (`..`) are rejected. Files over 10 GB are rejected to prevent resource exhaustion.
+**Input validation.** All file and folder paths are validated before use, on every tool that takes one — UNC paths (`\\server\share`) and directory traversal sequences (`..`) are rejected. Files over 10 GB are rejected to prevent resource exhaustion. `job_id` and `batch_id` are checked against the exact server-minted format before they are used to build any file path, so a crafted ID cannot traverse out of the jobs directory.
+
+**Transcript injection awareness.** Audio files can contain spoken content that, when transcribed, resembles instructions. Claude's built-in defenses handle this, but it is worth knowing that transcript content is treated as data — never as instructions — by the MCP server itself. Because transcribed content can still influence which tools Claude calls next, path/ID validation is applied defensively rather than trusting the single-user assumption alone.
 
-**Transcript injection awareness.** Audio files can contain spoken content that, when transcribed, resembles instructions. Claude's built-in defenses handle this, but it is worth knowing that transcript content is treated as data — never as instructions — by the MCP server itself.
+**Model downloads are restricted.** The `download_model` tool only downloads from two trusted Hugging Face namespaces (`ggerganov/whisper.cpp` and `ggml-org`). Arbitrary URLs are rejected. Redirects are validated against an allowlist before following. (Downloads are not yet verified against a per-model SHA256 digest — see SECURITY.md.)
 
-**Model downloads are restricted.** The `download_model` tool only downloads from two trusted Hugging Face namespaces (`ggerganov/whisper.cpp` and `ggml-org`). Arbitrary URLs are rejected. Redirects are validated against an allowlist before following.
+**Model selection is sandboxed.** Both `switch_model` and the `transcribe_audio` `model` override only accept `.bin` files within the configured models directory. Paths outside that directory are rejected via normalized path containment.
 
-**Model switching is sandboxed.** `switch_model` only accepts `.bin` files within the configured models directory. Paths outside that directory are rejected.
+**No PATH shadowing.** System binaries the server invokes on your behalf (`tasklist`, `wmic`) are called by absolute `System32` path so they can't be shadowed by a same-named executable earlier on `PATH`.
 
 See [SECURITY.md](SECURITY.md) for the full security policy.