10 KiB
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…).
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ą
- Parser SRT zapisuje linie czasu dosłownie. Model ich w ogóle nie widzi: dostaje tylko tekst z numerami (
[17] …). - Napisy idą partiami (domyślnie 25) razem z kilkoma poprzednimi (już przetłumaczonymi) i następnymi liniami jako kontekstem.
- Tryb JSON (domyślny): odpowiedź jest ograniczona schematem JSON (Ollama
format, LM Studio/OpenAIresponse_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ę. - 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.
- Formatowanie obejmujące cały napis (
{\an8},<i>…</i>) 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/downloadi 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)
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.