# Tłumacz napisów SRT Lokalna aplikacja webowa, która tłumaczy pliki `.srt` modelami LLM uruchomionymi u Ciebie: **Ollama**, **LM Studio** albo dowolny serwer **OpenAI-compatible** (llama.cpp `llama-server`, vLLM, KoboldCpp, Jan…). ```bash npm install # tylko @lmstudio/sdk (ładowanie modeli z KV-cache quant); bez niego też działa npm start # → http://127.0.0.1:8765 npm test ``` Wymaga Node.js ≥ 20. Serwer nie ma innych zależności. `PORT` i `HOST` można ustawić zmiennymi środowiskowymi. ## Jak to działa — czemu ramki czasowe się nie rozjadą 1. Parser SRT zapisuje linie czasu **dosłownie**. Model ich w ogóle nie widzi: dostaje tylko tekst z numerami (`[17] …`). 2. Napisy idą partiami (domyślnie 25) razem z kilkoma poprzednimi (już przetłumaczonymi) i następnymi liniami jako kontekstem. 3. **Tryb JSON (domyślny):** odpowiedź jest ograniczona schematem JSON (Ollama `format`, LM Studio/OpenAI `response_format: json_schema`) z dokładnie tymi kluczami, w tej kolejności. Klucz zawiera początek oryginału, np. `"17|The partner's office…"`. Gramatyka każe modelowi napisać go tuż przed tłumaczeniem, więc każda wartość jest przypięta do swojego napisu. To usuwa klasyczny błąd, w którym od jakiegoś miejsca wszystko jest przesunięte o jedną linię. 4. Wynik jest sprawdzany: czy nie brakuje id, czy odpowiedź nie została ucięta, czy model nie skopiował oryginału, nie scalił dwóch linii i nie powtarza tłumaczeń. Jeśli coś jest nie tak, partia jest dzielona na pół, a pojedyncze problematyczne linie idą osobno. Zdanie scalone z dwóch napisów (jedna linia pełna, druga pusta) jest dzielone automatycznie, proporcjonalnie do długości oryginałów. 5. Formatowanie obejmujące cały napis (`{\an8}`, `…`) jest zdejmowane przed tłumaczeniem i potem przywracane. Linie bez liter (`♪ ♪`) są kopiowane bez pytania modelu. Za długie linie są zawijane (domyślnie do 42 znaków, maks. 2 linie). Inne tryby: **numerowane linie** (dla serwerów bez structured output; odporny parser bierze ostatni kompletny blok odpowiedzi) i **po jednej linii**. Jeśli model „myśli na głos” i w trybie linii ucina odpowiedzi, zadanie samo przełącza się na JSON. **Piosenki (linie z ♪/♫ albo w starym stylu `# … #`)** mają trzy tryby: *tłumacz jak resztę*, *zostaw w oryginale* albo *usuń z napisów*. W dwóch ostatnich linie piosenek w ogóle nie trafiają do modelu (szybciej, mniej tokenów) i nie są używane jako kontekst. Usuwanie dzieje się przy eksporcie: napis z samą piosenką znika, a w napisie mieszanym („- ♪ Sto lat ♪ / - Przestań!”) usuwane są tylko linie piosenki. Pozostałe napisy zachowują dokładnie swoje czasy i są numerowane od nowa. Wieloliniowa zwrotka otwarta i zamknięta nutą w jednym napisie jest rozpoznawana w całości. Opisy dźwięków typu `[music playing]` nie są traktowane jako piosenki. Zmiana trybu nie wymaga ponownego tłumaczenia. W tabeli wyników tłumaczenia można edytować ręcznie, a każdą linię przetłumaczyć ponownie (↻). Podejrzane linie są oznaczane: za krótkie lub za długie względem oryginału, bez zmian, >2 linie, za długie linie, za szybkie do przeczytania (>21 znaków/s). Praca zapisuje się w przeglądarce, a „Dokończ brakujące” wznawia przerwane tłumaczenie. Eksport: samo tłumaczenie albo napisy dwujęzyczne, LF/CRLF, opcjonalny BOM. ## Kontekst, KV-cache i pamięć | | Długość kontekstu | Kwantyzacja KV-cache | Szacunek pamięci | |---|---|---|---| | **LM Studio** | przy ładowaniu modelu (przycisk „Załaduj model” albo automatycznie na starcie) | ✅ K i V osobno (`q8_0`, `q4_0`, …) przez `@lmstudio/sdk` | estymator LM Studio + własny | | **Ollama** | `num_ctx` w każdym zapytaniu (Ollama sama przeładuje model) | ustawienie serwera: `OLLAMA_FLASH_ATTENTION=1`, `OLLAMA_KV_CACHE_TYPE=q8_0` | własny + **rzeczywiste** użycie z `/api/ps` po załadowaniu | | **OpenAI-compat.** | przy starcie serwera (`llama-server -c 16384 -fa on -ctk q8_0 -ctv q8_0`) | argumenty serwera | własny (do planowania) | Własny szacunek liczy KV-cache warstwa po warstwie na podstawie metadanych GGUF: z Ollamy przez `/api/show`, a dla LM Studio z nagłówka pliku `.gguf` na dysku. Uwzględnia GQA, warstwy z przesuwnym oknem (Gemma), współdzielony KV-cache (Gemma 3n/4), modele hybrydowe z warstwami rekurencyjnymi (Qwen3.5/Qwen3-Next), MLA (DeepSeek) i typ kwantyzacji K/V. Na Apple Silicon budżet to `recommendedMaxWorkingSetSize` z Metal (ta sama wartość, której używają Ollama i llama.cpp; odczytywana raz przez `swift`, a gdy go nie ma, szacowana na ~74% RAM), albo `iogpu.wired_limit_mb`, jeśli go podniesiono. Na NVIDII to wynik `nvidia-smi`. Bufory obliczeniowe są przybliżone, więc dla LM Studio wiarygodniejszy jest jego własny estymator. Kwantyzacja V-cache w llama.cpp wymaga Flash Attention. `q8_0` praktycznie nie pogarsza jakości i zmniejsza KV-cache prawie o połowę. ## Pobieranie modeli z aplikacji W karcie „2. Model” → „Pobierz nowy model” wpisujesz nazwę i widzisz pasek postępu z prędkością i czasem do końca. Pobieranie trwa na serwerze, więc odświeżenie lub zamknięcie karty go nie przerywa (po powrocie pasek się podpina). Podpowiedzi tylko wpisują nazwę, a pobieranie startuje dopiero przyciskiem. Modele, które nie zmieszczą się w pamięci GPU, są oznaczone, a te już pobrane mają ✓. - **Ollama:** nazwy z biblioteki (`translategemma:12b`) albo dowolne repozytorium GGUF z Hugging Face (`hf.co/speakleash/Bielik-11B-v3.0-Instruct-GGUF:Q4_K_M`). Postęp przychodzi z `/api/pull`. Przerwanie zatrzymuje pobieranie, a ponowne pobranie wznawia je od miejsca przerwania. - **LM Studio:** nazwy z katalogu (`google/gemma-3-12b`) albo link do Hugging Face plus kwantyzacja (`POST /api/v1/models/download` i odpytywanie statusu). API LM Studio nie ma anulowania, więc pobieranie wstrzymuje się w panelu Downloads w samym LM Studio. - Silnik OpenAI-compatible nie ma ujednoliconego pobierania. ## Modele **Zwykłe LLM-y** (profil „Uniwersalny”) tłumaczą partiami z kontekstem: Gemma, Qwen, Llama, Mistral, Aya Expanse, a dla polskiego warto też spróbować Bielika (SpeakLeash). Rozumowanie („thinking”) jest domyślnie wyłączane (`think: false` w Ollamie, `reasoning_effort: "none"` w LM Studio), bo przy tłumaczeniu tylko spowalnia. **Dedykowane modele tłumaczeniowe** są rozpoznawane po nazwie (profil można też wybrać ręcznie). Dostają swój oficjalny szablon promptu i tłumaczą po jednym segmencie. Kwestie dialogowe (`- …`) idą linia po linii. | Profil | Przykłady | Uwagi | |---|---|---| | TranslateGemma | `ollama pull translategemma:4b` / `:12b` / `:27b` | wymaga języka źródłowego (aplikacja go wykrywa) | | Hunyuan-MT / HY-MT | `tencent/HY-MT1.5-7B` (GGUF od społeczności) | zalecane parametry ustawia przycisk „Zastosuj parametry zalecane” | | Seed-X | `ByteDance-Seed/Seed-X-PPO-7B` | | | Tower | `Unbabel/Tower-Plus-9B`, TowerInstruct | | Modele MT tłumaczą zdania bez szerszego kontekstu, więc przy rodzaju gramatycznym i zwrotach (ty/Pan) radzą sobie gorzej niż dobry LLM z kontekstem. Pole „Uwagi dla tłumacza” (płeć postaci, ton, słowniczek) trafia tylko do profilu uniwersalnego. ## API (dla skryptów) `POST /api/srt/parse` (surowe bajty pliku) → napisy · `POST /api/jobs` → id zadania · `GET /api/jobs/:id/events` (SSE) · `GET /api/jobs/:id` · `POST /api/jobs/:id/cancel` · `POST /api/srt/build` → plik SRT · `POST /api/engine/{status,models,model-info,estimate,load,unload,loaded}`. ## Struktura ``` server.js serwer HTTP + API (bez frameworka) src/srt.js parser/serializer SRT, wykrywanie kodowania, tagi, zawijanie src/translator.js zadanie tłumaczenia: partie, walidacja, podziały, naprawy src/prompts.js prompty, schemat JSON, szablony modeli MT, parser linii src/vram.js szacowanie pamięci z metadanych GGUF, pamięć systemu src/gguf.js czytnik nagłówka GGUF src/engines/ ollama.js, lmstudio.js, openai.js public/ interfejs (HTML/CSS/JS bez bundlera) samples/ przykładowe napisy ``` ## Wyniki testów (MacBook M4, 16 GB) | Model | Silnik | Tryb | 40 linii | Uwagi | |---|---|---|---|---| | gemma-4-e4b Q4_K_M | LM Studio | JSON, partie po 15 | ~40 s | najlepsza jakość z testowanych; potrafi „myśleć na głos” w trybie linii, więc najlepiej JSON | | translategemma:4b | Ollama | oficjalny szablon MT | ~25 s | szybka (~40 tok/s); bez kontekstu zgaduje rodzaj i ton, czasem przegaduje | | translategemma:4b | Ollama | JSON z kontekstem | ~34 s | trafniejsza w kontekście, ale daje warianty „byłeś/aś” (oznaczane w tabeli) | | qwen3.5-9b Q4_K_M | LM Studio | JSON | — | wolniejsza (~13 tok/s); 12 linii w ~15 s | Szacunek KV-cache porównany z logami llama.cpp (TranslateGemma 4B, 32k): f16 — 814 MiB (szacunek 0.79 GiB), q8_0 — 432 MiB (szacunek 0.42 GiB). Uwaga: Ollama 0.40 w `/api/ps` raportuje mniej, niż faktycznie zajmuje (pomija część KV-cache), dlatego aplikacja pokazuje tę wartość jako „Ollama raportuje”, z ostrzeżeniem, gdy jest niespójna. ## Plik wykonywalny (bez instalowania Node.js) ```bash npm run build:win # → dist/srt-translator-win-x64.zip (srt-translator.exe + JAK-URUCHOMIC.txt) npm run build:mac # → dist/srt-translator-darwin-arm64.zip ``` Skrypt `scripts/build-exe.mjs` łączy serwer i wszystkie moduły w jeden plik (esbuild), a interfejs (`public/`) dodaje jako zasoby. Potem wstrzykuje to do oficjalnej binarki Node.js dla systemu docelowego (Node.js Single Executable Application). Binarki są pobierane raz z nodejs.org do `build/cache` i sprawdzane sumą SHA-256. Node z Homebrew ma wyłączone SEA, więc do samego budowania skrypt używa wtedy oficjalnego Node dla bieżącego systemu. Wersja Node uruchamiającego skrypt musi zgadzać się z wersją binarki docelowej. Gotowy program uruchamia serwer, otwiera przeglądarkę i, jeśli 8765 jest zajęty, sam bierze następny wolny port. Pliki nie są podpisane, więc Windows SmartScreen („Więcej informacji” → „Uruchom mimo to”) i macOS Gatekeeper (prawy klik → Otwórz) pytają przy pierwszym uruchomieniu.