From ab9cd73ad52650c92fab91982c7e1e3dd24af8a4 Mon Sep 17 00:00:00 2001 From: Giovanny Aranda Date: Fri, 23 Oct 2026 15:39:34 +0200 Subject: [PATCH 1/6] feat: add OpenAI-compatible LLM translation provider with background jobs - Add TRANSLATION_PROVIDER=llm using any OpenAI-compatible chat API (OpenAI, OpenRouter, Anthropic, LiteLLM, Ollama). Only subtitle text is sent to the model as JSON; timestamps never leave the server. - Bundle a default system prompt, overridable by mounting /config/llm-system-prompt.txt (or LLM_PROMPT_FILE). - Validate a strict 1:1 id mapping, retry malformed batches and split them in half; retry rate limits and server errors with backoff. - Run translations as queued background jobs with batch progress, so long LLM runs no longer hit the 60s proxy timeout. Progress survives page reloads and Plex is refreshed server-side when a job finishes. - Show LLM model and token usage in the header. Closes #3 --- .gitignore | 3 + README.md | 47 +++++- docker-compose.yml | 8 +- server/prompts/llm-system-prompt.txt | 24 +++ server/routes/subtitle.js | 124 +++++---------- server/routes/usage.js | 4 +- server/services/deepl.js | 71 +-------- server/services/jobs.js | 101 ++++++++++++ server/services/llm.js | 216 ++++++++++++++++++++++++++ server/services/translator.js | 94 +++++++++++ src/App.tsx | 16 +- src/components/ApiUsage.tsx | 12 +- src/components/SubtitleTranslator.tsx | 22 +-- src/components/TranslationJobs.tsx | 114 ++++++++++++++ src/components/VideoExtractor.tsx | 21 +-- src/lib/api.ts | 24 +-- src/types/index.ts | 26 +++- 17 files changed, 717 insertions(+), 210 deletions(-) create mode 100644 server/prompts/llm-system-prompt.txt create mode 100644 server/services/jobs.js create mode 100644 server/services/llm.js create mode 100644 server/services/translator.js create mode 100644 src/components/TranslationJobs.tsx diff --git a/.gitignore b/.gitignore index 7570cb4..773576a 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,6 @@ dist data/ *.tsbuildinfo .smbdelete* + +# Local secrets +.env diff --git a/README.md b/README.md index 827af1f..6337b3f 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,18 @@ The application offers optional integration with a Plex server, allowing you to | Variable | Description | Required | |----------------|-------------------------------------------|----------| -| `DEEPL_API_KEY` | Your DeepL API key | Yes | +| `TRANSLATION_PROVIDER` | Translation engine: `deepl` (default) or `llm` | Optional | +| `DEEPL_API_KEY` | Your DeepL API key | Yes, with `deepl` | +| `LLM_BASE_URL` | OpenAI-compatible API base URL (default `https://api.openai.com/v1`) | Optional | +| `LLM_API_KEY` | API key for the LLM endpoint | Yes, with `llm` (except local servers) | +| `LLM_MODEL` | Model name, e.g. `gpt-4.1`, `anthropic/claude-sonnet-5-5` | Yes, with `llm` | +| `LLM_BATCH_SIZE` | Subtitles per request (default `25`) | Optional | +| `LLM_CONTEXT_SIZE` | Previous lines sent as context (default `5`) | Optional | +| `LLM_CONCURRENCY` | Parallel requests (default `3`) | Optional | +| `LLM_MAX_RETRIES` | Retries for rate limits and server errors (default `5`) | Optional | +| `LLM_TEMPERATURE` | Sampling temperature (default `0.2`) | Optional | +| `LLM_JSON_MODE` | Send `response_format: json_object`; set `false` if your endpoint rejects it (default `true`) | Optional | +| `LLM_PROMPT_FILE` | Path to a custom system prompt (default `/config/llm-system-prompt.txt`) | Optional | | `PLEX_HOST` | Plex server hostname or IP address | Optional | | `PLEX_PORT` | Plex server port | Optional | | `PLEX_TOKEN` | Plex API token | Optional | @@ -73,6 +84,35 @@ The application offers optional integration with a Plex server, allowing you to --- +## Using an LLM Instead of DeepL + +Set `TRANSLATION_PROVIDER=llm` to translate with any OpenAI-compatible chat API. The SRT +file is parsed on the server and only the subtitle text is sent to the model, so timestamps +and numbering are never altered. + +| Provider | `LLM_BASE_URL` | `LLM_MODEL` example | +|----------|----------------|---------------------| +| OpenAI | `https://api.openai.com/v1` | `gpt-4.1` | +| OpenRouter | `https://openrouter.ai/api/v1` | `anthropic/claude-sonnet-5-5` | +| Anthropic (OpenAI SDK compatibility) | `https://api.anthropic.com/v1` | `claude-sonnet-5-5` | +| LiteLLM proxy | `http://litellm:4000/v1` | any model configured in LiteLLM | +| Ollama | `http://ollama:11434/v1` | `qwen2.5:14b` | + +### Custom system prompt + +The bundled prompt lives in [`server/prompts/llm-system-prompt.txt`](server/prompts/llm-system-prompt.txt). +To use your own, mount a file at `/config/llm-system-prompt.txt` (or point `LLM_PROMPT_FILE` +elsewhere). It is read on every translation, so changes apply without restarting. The +placeholders `{{SOURCE_LANG}}` and `{{TARGET_LANG}}` are replaced with the language names, and +the model must answer with `{"items":[{"i":,"t":""}]}`. + +```yaml +volumes: + - ./llm-system-prompt.txt:/config/llm-system-prompt.txt:ro +``` + +--- + ## How to Get a Plex Token 1. Open your Plex server in a browser and log in. @@ -98,6 +138,11 @@ For detailed instructions, refer to the official [Plex Token Documentation](http 3. Set up the `.env` file with the required variables: ```env DEEPL_API_KEY= + # Or, to use an LLM: + # TRANSLATION_PROVIDER=llm + # LLM_BASE_URL=https://openrouter.ai/api/v1 + # LLM_API_KEY= + # LLM_MODEL=anthropic/claude-sonnet-5-5 PLEX_HOST= PLEX_PORT= PLEX_TOKEN= diff --git a/docker-compose.yml b/docker-compose.yml index a8fc7df..eaac548 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -7,10 +7,16 @@ services: - "3000:3000" # Backend API port - "5173:5173" # Frontend dev server port environment: + - TRANSLATION_PROVIDER=${TRANSLATION_PROVIDER:-deepl} - DEEPL_API_KEY=${DEEPL_API_KEY} + - LLM_BASE_URL=${LLM_BASE_URL} + - LLM_API_KEY=${LLM_API_KEY} + - LLM_MODEL=${LLM_MODEL} - PLEX_HOST=${PLEX_HOST} - PLEX_PORT=${PLEX_PORT} - PLEX_TOKEN=${PLEX_TOKEN} volumes: - ./data:/data - - ./movies:/movies \ No newline at end of file + - ./movies:/movies + # Optional: custom LLM system prompt (falls back to the bundled one) + # - ./llm-system-prompt.txt:/config/llm-system-prompt.txt:ro \ No newline at end of file diff --git a/server/prompts/llm-system-prompt.txt b/server/prompts/llm-system-prompt.txt new file mode 100644 index 0000000..ef2dfd7 --- /dev/null +++ b/server/prompts/llm-system-prompt.txt @@ -0,0 +1,24 @@ +You are a professional subtitle translator for films and TV series. +Translate subtitles from {{SOURCE_LANG}} to {{TARGET_LANG}}. + +Rules: +- Translate meaning, not words. Use the surrounding dialogue ("context") and the + title of the work ("title", when given) to resolve ambiguity, pronouns, gender, + formality and tone. +- Adapt idioms, jokes, slang and insults to natural equivalents in {{TARGET_LANG}}; + never translate them literally if the result makes no sense. +- Keep each subtitle concise and readable, with a similar length to the original. +- Keep proper names, places and brand names unless they have a well-established + translation. Be consistent with names and terms across the whole file. +- Preserve formatting tags (, , , {\an8}), music notes (♪) and + speaker dashes ("- ") exactly as they appear. Keep line breaks (\n) inside an + entry where they make sense. +- Translate sound descriptions such as [door slams] too, keeping the brackets. +- Do not merge, split, add, omit or reorder entries. Return exactly one output per + input id, even if the entry is a single word or a name. +- Entries in "context" are earlier lines for reference only; do not translate or + return them. + +Output ONLY a JSON object with this exact shape, and nothing else: +{"items":[{"i":,"t":""}]} +The ids must be exactly the same as the ids in the "translate" array. diff --git a/server/routes/subtitle.js b/server/routes/subtitle.js index a7d614a..d1e8a04 100644 --- a/server/routes/subtitle.js +++ b/server/routes/subtitle.js @@ -1,93 +1,55 @@ import { Router } from 'express'; import { join } from 'path'; -import { translateSRT } from '../services/deepl.js'; +import { existsSync } from 'fs'; +import { getConfigError } from '../services/translator.js'; +import { createTranslationJob, getJob, listJobs } from '../services/jobs.js'; import { extractSubtitles } from '../services/ffmpeg.js'; import { DATA_DIR, MOVIES_DIR } from '../utils/paths.js'; const router = Router(); -router.post('/translate_subtitle', async (req, res) => { - try { - const { serie, season, srt_path, source_lang, target_lang, type } = req.body; - - if (type === 'series' && (!serie || !season || !srt_path || !source_lang || !target_lang)) { - return res.status(400).json({ error: 'Missing required parameters' }); - } - else if (type === 'movies' && (!serie || !srt_path || !source_lang || !target_lang)) { - return res.status(400).json({ error: 'Missing parameters' }); - } +router.post('/translate_subtitle', (req, res) => { + const { serie, season, srt_path, source_lang, target_lang, type, update_plex } = req.body; - if (!process.env.DEEPL_API_KEY) { - return res.status(400).json({ message: 'DeepL API key not configured' }); - } - - let subtitlePath; - if (type === 'series') { - subtitlePath = join(DATA_DIR, serie, season, srt_path); - } else { - subtitlePath = join(MOVIES_DIR, serie, srt_path); - } - - const translatedPath = await translateSRT(subtitlePath, source_lang, target_lang); + if (type === 'series' && (!serie || !season || !srt_path || !source_lang || !target_lang)) { + return res.status(400).json({ message: 'Missing required parameters' }); + } + else if (type === 'movies' && (!serie || !srt_path || !source_lang || !target_lang)) { + return res.status(400).json({ message: 'Missing parameters' }); + } - res.json({ path: translatedPath }); - } catch (error) { - console.error('Error in subtitle translation:', error); - - // Format status code based on the error - let statusCode = 500; - if (error.status) { - statusCode = error.status; - } - - // Specific handling for size errors - if (error.message && error.message.includes('exceeds the size limit')) { - return res.status(statusCode).json({ - message: 'The SRT file is too large to translate in a single operation. Please try again so it can be processed in smaller parts.', - originalError: error.toString(), - isLargeFile: true - }); - } - - // Authentication errors - if (error.response && error.response.status === 403) { - return res.status(403).json({ - message: 'Authentication failed with DeepL API. Please check your API key.', - originalError: error.toString() - }); - } - - // API limit errors - if (error.message && (error.message.includes('quota') || error.message.includes('limit'))) { - return res.status(statusCode).json({ - message: 'DeepL API quota exceeded. Please try again later or upgrade your DeepL subscription.', - originalError: error.toString() - }); - } - - // Handle DeepL-specific errors with more details - if (error.deeplRequest) { - // This is a enhanced error from our DeepL service - return res.status(statusCode).json({ - message: `DeepL translation failed: ${error.message}`, - originalError: error.toString(), - apiDetails: error.apiDetails || null, - deeplRequest: error.deeplRequest, - status: error.status || 500, - stack: error.stack - }); - } - - // Format a user-friendly error message with technical details - const userMessage = 'Translation failed: ' + (error.message || 'Unknown error'); - - res.status(statusCode).json({ - message: userMessage, - originalError: error.toString(), - apiDetails: error.apiDetails || null, - status: error.status || 500, - stack: error.stack - }); + const configError = getConfigError(); + if (configError) { + return res.status(400).json({ message: configError }); + } + + const subtitlePath = type === 'series' + ? join(DATA_DIR, serie, season, srt_path) + : join(MOVIES_DIR, serie, srt_path); + if (!existsSync(subtitlePath)) { + return res.status(404).json({ message: `Subtitle file not found: ${srt_path}` }); + } + + // Translation can take minutes with an LLM, so it runs as a background job + const job = createTranslationJob({ + subtitlePath, + sourceLang: source_lang, + targetLang: target_lang, + title: serie, + updatePlex: update_plex, + }); + res.status(202).json(job); +}); + +router.get('/jobs', (req, res) => { + res.json(listJobs()); +}); + +router.get('/jobs/:id', (req, res) => { + const job = getJob(req.params.id); + if (!job) { + return res.status(404).json({ message: 'Job not found' }); } + res.json(job); }); router.post('/extract_subtitles', async (req, res) => { diff --git a/server/routes/usage.js b/server/routes/usage.js index c8a89de..323a0a5 100644 --- a/server/routes/usage.js +++ b/server/routes/usage.js @@ -1,11 +1,11 @@ import { Router } from 'express'; -import { getUsageStats } from '../services/deepl.js'; +import { getUsage } from '../services/translator.js'; const router = Router(); router.get('/get_character_count', async (req, res) => { try { - const stats = await getUsageStats(); + const stats = await getUsage(); res.json(stats); } catch (error) { res.status(500).json({ diff --git a/server/services/deepl.js b/server/services/deepl.js index 64a426f..cc7c5bf 100644 --- a/server/services/deepl.js +++ b/server/services/deepl.js @@ -100,7 +100,7 @@ async function downloadDocument(documentId, documentKey, outputPath) { throw error; // Rethrow to be handled by the calling function } } -function getTranslatedFilePath(originalPath, sourceLang, targetLang) { +export function getTranslatedFilePath(originalPath, sourceLang, targetLang) { const { dir, name, ext } = parse(originalPath); // Remove source language code if present (e.g., "myfile.en.srt" -> "myfile") @@ -388,7 +388,7 @@ export async function translateLargeDocument(filePath, sourceLang, targetLang) { * @param {string} targetLang Target language * @returns {Promise} Array of translated strings in the same order */ -async function translateTexts(texts, sourceLang, targetLang) { +export async function translateTexts(texts, sourceLang, targetLang) { const response = await axios.post( `${DEEPL_API_URL}/translate`, { text: texts, source_lang: sourceLang, target_lang: targetLang }, @@ -411,7 +411,7 @@ const TEXT_API_MAX_BYTES = 100 * 1024; // 100KB safety margin under the 128KB li * @param {string[]} texts Array of text strings * @returns {string[][]} Array of batches */ -function buildTextBatches(texts) { +export function buildTextBatches(texts) { const batches = []; let currentBatch = []; let currentBytes = 0; @@ -439,71 +439,6 @@ function buildTextBatches(texts) { return batches; } -/** - * Translates an SRT file using the DeepL Text API, guaranteeing 1:1 mapping - * between original and translated subtitle blocks. - * @param {string} filePath Path to the SRT file - * @param {string} sourceLang Source language - * @param {string} targetLang Target language - * @returns {Promise} Path to the translated file - */ -export async function translateSRT(filePath, sourceLang, targetLang) { - const fileContent = fs.readFileSync(filePath, 'utf-8'); - const subtitles = parseSRT(fileContent); - console.log(`Translating ${subtitles.length} subtitle blocks via Text API`); - - // Separate non-empty subtitles (to be translated) from empty ones (kept as-is). - // We track the original index so we can map translations back correctly. - const toTranslate = []; // { originalIndex, text } - for (let i = 0; i < subtitles.length; i++) { - if (subtitles[i].text.trim() !== '') { - toTranslate.push({ originalIndex: i, text: subtitles[i].text }); - } - } - - // Replace newlines with space so DeepL receives each subtitle as a single - // sentence with full context, instead of treating each line independently. - const multilineCount = toTranslate.filter(item => item.text.includes('\n')).length; - if (multilineCount > 0) { - console.log(`Normalizing ${multilineCount} multi-line subtitles: removing line breaks so DeepL retains context between lines`); - } - const texts = toTranslate.map(item => item.text.replace(/\n/g, ' ')); - const batches = buildTextBatches(texts); - console.log(`Sending ${texts.length} non-empty texts in ${batches.length} batch(es)`); - - // Translate batches sequentially and collect results in order - const translatedTexts = []; - for (let i = 0; i < batches.length; i++) { - console.log(`Translating batch ${i + 1}/${batches.length} (${batches[i].length} texts)...`); - try { - const results = await translateTexts(batches[i], sourceLang, targetLang); - translatedTexts.push(...results); - } catch (error) { - console.error(`Error translating batch ${i + 1}:`, error.message); - if (error.response) { - console.error('DeepL API Error Status:', error.response.status); - console.error('DeepL API Error Response:', error.response.data); - const msg = error.response.data?.message || `API Error (${error.response.status})`; - const enhanced = new Error(msg); - enhanced.status = error.response.status; - enhanced.apiDetails = error.response.data; - throw enhanced; - } - throw error; - } - } - - // Map translations back to the original subtitle array - for (let i = 0; i < toTranslate.length; i++) { - subtitles[toTranslate[i].originalIndex].text = translatedTexts[i]; - } - - const outputPath = getTranslatedFilePath(filePath, sourceLang, targetLang); - fs.writeFileSync(outputPath, stringifySRT(subtitles)); - console.log(`Translation complete: ${outputPath}`); - return outputPath; -} - /** * Splits an array of subtitles into smaller chunks that don't exceed the character limit * @param {Array} subtitles Array of subtitle objects diff --git a/server/services/jobs.js b/server/services/jobs.js new file mode 100644 index 0000000..bf434c0 --- /dev/null +++ b/server/services/jobs.js @@ -0,0 +1,101 @@ +import { randomUUID } from 'crypto'; +import { basename } from 'path'; +import { translateSRT } from './translator.js'; +import { isConfigured as isPlexConfigured, updateLibrary } from './plexService.js'; + +const MAX_FINISHED_JOBS = 20; + +// In-memory job store: survives page reloads, not server restarts +const jobs = new Map(); +const queue = []; +let running = false; + +function toPublic(job) { + const { subtitlePath: _subtitlePath, ...rest } = job; + return rest; +} + +function pruneFinished() { + const finished = [...jobs.values()].filter(job => job.status === 'done' || job.status === 'error'); + for (const job of finished.slice(0, Math.max(0, finished.length - MAX_FINISHED_JOBS))) { + jobs.delete(job.id); + } +} + +async function runJob(job) { + job.status = 'running'; + job.startedAt = new Date().toISOString(); + try { + job.path = await translateSRT(job.subtitlePath, job.sourceLang, job.targetLang, { + title: job.title, + onProgress: (done, total) => { + job.progress = { done, total }; + }, + }); + + if (job.updatePlex && isPlexConfigured()) { + try { + await updateLibrary(); + job.plex = 'updated'; + } catch (error) { + job.plex = 'failed'; + job.plexError = error.message; + } + } else { + job.plex = 'skipped'; + } + job.status = 'done'; + } catch (error) { + console.error(`Translation job ${job.id} failed:`, error.message); + job.status = 'error'; + job.error = { + message: error.message || 'Unknown error', + status: error.status || 500, + apiDetails: error.apiDetails || null, + }; + } finally { + job.finishedAt = new Date().toISOString(); + } +} + +async function processQueue() { + if (running) return; + running = true; + while (queue.length > 0) { + await runJob(queue.shift()); + pruneFinished(); + } + running = false; +} + +/** + * Queues a subtitle translation. Jobs run one at a time. + */ +export function createTranslationJob({ subtitlePath, sourceLang, targetLang, title, updatePlex }) { + const job = { + id: randomUUID(), + status: 'queued', + file: basename(subtitlePath), + title, + sourceLang, + targetLang, + updatePlex: !!updatePlex, + progress: { done: 0, total: 0 }, + createdAt: new Date().toISOString(), + subtitlePath, + }; + jobs.set(job.id, job); + queue.push(job); + processQueue(); + return toPublic(job); +} + +export function getJob(id) { + const job = jobs.get(id); + return job ? toPublic(job) : null; +} + +/** Most recent first. */ +export function listJobs() { + return [...jobs.values()].reverse().map(toPublic); +} diff --git a/server/services/llm.js b/server/services/llm.js new file mode 100644 index 0000000..9098717 --- /dev/null +++ b/server/services/llm.js @@ -0,0 +1,216 @@ +import fs from 'fs'; +import axios from 'axios'; +import { dirname, join } from 'path'; +import { fileURLToPath } from 'url'; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const DEFAULT_PROMPT_PATH = join(__dirname, '..', 'prompts', 'llm-system-prompt.txt'); +const CUSTOM_PROMPT_PATH = process.env.LLM_PROMPT_FILE || '/config/llm-system-prompt.txt'; + +const BASE_URL = (process.env.LLM_BASE_URL || 'https://api.openai.com/v1').replace(/\/+$/, ''); +const BATCH_SIZE = parseInt(process.env.LLM_BATCH_SIZE || '25', 10); +const CONTEXT_SIZE = parseInt(process.env.LLM_CONTEXT_SIZE || '5', 10); +const CONCURRENCY = parseInt(process.env.LLM_CONCURRENCY || '3', 10); +const TEMPERATURE = parseFloat(process.env.LLM_TEMPERATURE || '0.2'); +const JSON_MODE = process.env.LLM_JSON_MODE !== 'false'; +const REQUEST_TIMEOUT = 180000; // 3 minutes per request +const MAX_HTTP_RETRIES = parseInt(process.env.LLM_MAX_RETRIES || '5', 10); + +// Tokens consumed since the server started (shown in the UI) +const usage = { prompt_tokens: 0, completion_tokens: 0 }; + +export function getLLMConfigError() { + if (!process.env.LLM_API_KEY && !process.env.LLM_BASE_URL) { + return 'LLM provider not configured: set LLM_API_KEY (and LLM_BASE_URL for non-OpenAI endpoints)'; + } + if (!process.env.LLM_MODEL) { + return 'LLM provider not configured: set LLM_MODEL'; + } + return null; +} + +export function getLLMUsage() { + return { + provider: 'llm', + model: process.env.LLM_MODEL || null, + prompt_tokens: usage.prompt_tokens, + completion_tokens: usage.completion_tokens, + }; +} + +function languageName(code) { + try { + return new Intl.DisplayNames(['en'], { type: 'language' }).of(code) || code; + } catch { + return code; + } +} + +/** + * Loads the system prompt. A mounted custom prompt file takes precedence over + * the bundled default. Read on every translation so edits apply without restart. + */ +function loadSystemPrompt(sourceLang, targetLang) { + let template; + if (fs.existsSync(CUSTOM_PROMPT_PATH)) { + console.log(`Using custom LLM system prompt: ${CUSTOM_PROMPT_PATH}`); + template = fs.readFileSync(CUSTOM_PROMPT_PATH, 'utf-8'); + } else { + template = fs.readFileSync(DEFAULT_PROMPT_PATH, 'utf-8'); + } + return template + .replaceAll('{{SOURCE_LANG}}', languageName(sourceLang)) + .replaceAll('{{TARGET_LANG}}', languageName(targetLang)); +} + +async function chatCompletion(systemPrompt, userContent) { + const body = { + model: process.env.LLM_MODEL, + temperature: TEMPERATURE, + messages: [ + { role: 'system', content: systemPrompt }, + { role: 'user', content: userContent }, + ], + }; + if (JSON_MODE) { + body.response_format = { type: 'json_object' }; + } + + for (let attempt = 1; ; attempt++) { + try { + const response = await axios.post(`${BASE_URL}/chat/completions`, body, { + headers: { + 'Content-Type': 'application/json', + ...(process.env.LLM_API_KEY && { Authorization: `Bearer ${process.env.LLM_API_KEY}` }), + }, + timeout: REQUEST_TIMEOUT, + }); + usage.prompt_tokens += response.data.usage?.prompt_tokens || 0; + usage.completion_tokens += response.data.usage?.completion_tokens || 0; + const content = response.data.choices?.[0]?.message?.content; + if (typeof content !== 'string') { + throw new Error('LLM response has no message content'); + } + return content; + } catch (error) { + const status = error.response?.status; + const retryable = !status || status === 429 || status >= 500; + if (!retryable || attempt >= MAX_HTTP_RETRIES) { + if (error.response) { + const apiMessage = error.response.data?.error?.message || `API Error (${status})`; + const enhanced = new Error(`LLM API error: ${apiMessage}`); + enhanced.status = status; + enhanced.apiDetails = error.response.data; + throw enhanced; + } + // Network failure: flag it as an HTTP-level error so batches are not split + const enhanced = new Error(`LLM API unreachable: ${error.code || error.message}`); + enhanced.status = 503; + throw enhanced; + } + // Honor Retry-After when present, otherwise exponential backoff capped at 30s + const retryAfter = parseInt(error.response?.headers?.['retry-after'], 10); + const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(2000 * 2 ** (attempt - 1), 30000); + console.warn(`LLM request failed (${status || error.code}), retrying in ${delay / 1000}s...`); + await new Promise((resolve) => setTimeout(resolve, delay)); + } + } +} + +function parseItems(content) { + // Tolerate models that wrap the JSON in code fences or add stray text + const start = content.indexOf('{'); + const end = content.lastIndexOf('}'); + const snippet = content.slice(0, 200).replace(/\s+/g, ' '); + if (start === -1 || end === -1) { + throw new Error(`LLM response is not JSON: "${snippet}"`); + } + let parsed; + try { + parsed = JSON.parse(content.slice(start, end + 1)); + } catch (error) { + throw new Error(`${error.message}: "${snippet}"`); + } + if (!Array.isArray(parsed.items)) { + throw new Error('LLM response has no "items" array'); + } + return parsed.items; +} + +/** + * Translates one batch, validating a strict 1:1 id mapping. On a malformed + * response it retries once, then splits the batch in half. + */ +async function translateBatch(systemPrompt, entries, context, title) { + const payload = { + ...(title && { title }), + context: context.map(({ i, t }) => ({ i, t })), + translate: entries.map(({ i, t }) => ({ i, t })), + }; + + let lastError; + for (let attempt = 1; attempt <= 2; attempt++) { + try { + const items = parseItems(await chatCompletion(systemPrompt, JSON.stringify(payload))); + const byId = new Map(items.map((item) => [Number(item.i), item.t])); + const missing = entries.filter(({ i }) => typeof byId.get(i) !== 'string'); + if (missing.length > 0) { + throw new Error(`LLM response is missing ${missing.length} of ${entries.length} entries`); + } + return entries.map(({ i }) => byId.get(i)); + } catch (error) { + if (error.status) throw error; // HTTP errors were already retried + lastError = error; + console.warn(`Invalid LLM batch response (attempt ${attempt}): ${error.message}`); + } + } + + if (entries.length === 1) { + throw new Error(`LLM translation failed: ${lastError.message}`); + } + const mid = Math.ceil(entries.length / 2); + console.warn(`Splitting batch of ${entries.length} entries in two`); + const first = await translateBatch(systemPrompt, entries.slice(0, mid), context, title); + const second = await translateBatch(systemPrompt, entries.slice(mid), entries.slice(Math.max(0, mid - CONTEXT_SIZE), mid), title); + return [...first, ...second]; +} + +/** + * Translates an array of subtitle texts with an OpenAI-compatible chat API. + * @param {string[]} texts Texts to translate + * @param {string} sourceLang Source language code + * @param {string} targetLang Target language code + * @param {{title?: string, onProgress?: (done: number, total: number) => void}} options + * Extra context for the model and a batch progress callback + * @returns {Promise} Translations in the same order + */ +export async function translateTextsLLM(texts, sourceLang, targetLang, { title, onProgress } = {}) { + const systemPrompt = loadSystemPrompt(sourceLang, targetLang); + const entries = texts.map((t, i) => ({ i, t })); + + const batches = []; + for (let start = 0; start < entries.length; start += BATCH_SIZE) { + batches.push({ + entries: entries.slice(start, start + BATCH_SIZE), + // Source lines before the batch, so batches can run concurrently + context: entries.slice(Math.max(0, start - CONTEXT_SIZE), start), + }); + } + console.log(`Translating ${texts.length} texts with ${process.env.LLM_MODEL} in ${batches.length} batch(es)`); + + const results = new Array(batches.length); + let next = 0; + let done = 0; + onProgress?.(0, batches.length); + const worker = async () => { + while (next < batches.length) { + const index = next++; + results[index] = await translateBatch(systemPrompt, batches[index].entries, batches[index].context, title); + console.log(`LLM batch ${++done}/${batches.length} done`); + onProgress?.(done, batches.length); + } + }; + await Promise.all(Array.from({ length: Math.min(CONCURRENCY, batches.length) }, worker)); + + return results.flat(); +} diff --git a/server/services/translator.js b/server/services/translator.js new file mode 100644 index 0000000..057ac4a --- /dev/null +++ b/server/services/translator.js @@ -0,0 +1,94 @@ +import fs from 'fs'; +import { parseSRT, stringifySRT } from '../utils/srt.js'; +import { buildTextBatches, getTranslatedFilePath, getUsageStats, translateTexts } from './deepl.js'; +import { getLLMConfigError, getLLMUsage, translateTextsLLM } from './llm.js'; + +export function getProvider() { + return (process.env.TRANSLATION_PROVIDER || 'deepl').toLowerCase() === 'llm' ? 'llm' : 'deepl'; +} + +/** + * @returns {string|null} A configuration error for the active provider, or null + */ +export function getConfigError() { + if (getProvider() === 'llm') { + return getLLMConfigError(); + } + return process.env.DEEPL_API_KEY ? null : 'DeepL API key not configured'; +} + +export async function getUsage() { + if (getProvider() === 'llm') { + return getLLMUsage(); + } + return { provider: 'deepl', ...(await getUsageStats()) }; +} + +async function translateWithDeepL(texts, sourceLang, targetLang, { onProgress } = {}) { + // Replace newlines with space so DeepL receives each subtitle as a single + // sentence with full context, instead of treating each line independently. + const normalized = texts.map(text => text.replace(/\n/g, ' ')); + const batches = buildTextBatches(normalized); + console.log(`Sending ${normalized.length} non-empty texts to DeepL in ${batches.length} batch(es)`); + + const translatedTexts = []; + onProgress?.(0, batches.length); + for (let i = 0; i < batches.length; i++) { + console.log(`Translating batch ${i + 1}/${batches.length} (${batches[i].length} texts)...`); + try { + translatedTexts.push(...await translateTexts(batches[i], sourceLang, targetLang)); + onProgress?.(i + 1, batches.length); + } catch (error) { + console.error(`Error translating batch ${i + 1}:`, error.message); + if (error.response) { + console.error('DeepL API Error Status:', error.response.status); + console.error('DeepL API Error Response:', error.response.data); + const msg = error.response.data?.message || `API Error (${error.response.status})`; + const enhanced = new Error(msg); + enhanced.status = error.response.status; + enhanced.apiDetails = error.response.data; + throw enhanced; + } + throw error; + } + } + return translatedTexts; +} + +/** + * Translates an SRT file with the configured provider, guaranteeing 1:1 mapping + * between original and translated subtitle blocks. Timestamps never leave the server. + * @param {string} filePath Path to the SRT file + * @param {string} sourceLang Source language + * @param {string} targetLang Target language + * @param {{title?: string, onProgress?: (done: number, total: number) => void}} options + * Extra context for the LLM provider and a batch progress callback + * @returns {Promise} Path to the translated file + */ +export async function translateSRT(filePath, sourceLang, targetLang, options = {}) { + const subtitles = parseSRT(fs.readFileSync(filePath, 'utf-8')); + const provider = getProvider(); + console.log(`Translating ${subtitles.length} subtitle blocks with provider: ${provider}`); + + // Only non-empty subtitles are translated; track the original index to map back. + const toTranslate = []; + for (let i = 0; i < subtitles.length; i++) { + if (subtitles[i].text.trim() !== '') { + toTranslate.push({ originalIndex: i, text: subtitles[i].text }); + } + } + const texts = toTranslate.map(item => item.text); + + const translatedTexts = provider === 'llm' + ? await translateTextsLLM(texts, sourceLang, targetLang, options) + : await translateWithDeepL(texts, sourceLang, targetLang, options); + + for (let i = 0; i < toTranslate.length; i++) { + subtitles[toTranslate[i].originalIndex].text = translatedTexts[i]; + } + + const outputPath = getTranslatedFilePath(filePath, sourceLang, targetLang); + fs.writeFileSync(outputPath, stringifySRT(subtitles)); + console.log(`Translation complete: ${outputPath}`); + return outputPath; +} diff --git a/src/App.tsx b/src/App.tsx index 6e2c844..15d7ec4 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -6,6 +6,7 @@ import { ShowSelector } from './components/ShowSelector'; import { SubtitleTranslator } from './components/SubtitleTranslator'; import { VideoExtractor } from './components/VideoExtractor'; import { TranslationStatus } from './components/TranslationStatus'; +import { TranslationJobs } from './components/TranslationJobs'; export function App() { const [mediaType, setMediaType] = useState<'series' | 'movies'>('series'); @@ -17,7 +18,6 @@ export function App() { const [subtitlePath, setSubtitlePath] = useState(''); const [videoPath, setVideoPath] = useState(''); const [error, setError] = useState(null); - const [translatedPath, setTranslatedPath] = useState(null); return (
@@ -36,7 +36,6 @@ export function App() { setSubtitlePath(''); setVideoPath(''); setError(null); - setTranslatedPath(null); }} /> @@ -62,12 +61,10 @@ export function App() { targetLang={targetLang} onSourceLangChange={setSourceLang} onTargetLangChange={setTargetLang} - onTranslationComplete={(path) => setTranslatedPath(path)} onError={setError} onClearStatus={() => { setError(null); - setTranslatedPath(null); - }} + }} /> ) : ( setTranslatedPath(path)} onError={setError} onClearStatus={() => { setError(null); - setTranslatedPath(null); - }} + }} /> )} + +
diff --git a/src/components/ApiUsage.tsx b/src/components/ApiUsage.tsx index 019a7e9..88716a7 100644 --- a/src/components/ApiUsage.tsx +++ b/src/components/ApiUsage.tsx @@ -12,19 +12,25 @@ export function ApiUsage() { if (!data) return null; + const isLLM = data.provider === 'llm'; + return (
-
API Usage
+
+ {isLLM ? `LLM · ${data.model ?? 'unknown model'}` : 'API Usage'} +
- {data.character_count}/{data.character_limit} + {isLLM + ? `${((data.prompt_tokens ?? 0) + (data.completion_tokens ?? 0)).toLocaleString()} tokens` + : `${data.character_count}/${data.character_limit}`}
diff --git a/src/components/SubtitleTranslator.tsx b/src/components/SubtitleTranslator.tsx index 89fd4cb..36d33b6 100644 --- a/src/components/SubtitleTranslator.tsx +++ b/src/components/SubtitleTranslator.tsx @@ -17,7 +17,6 @@ interface Props { targetLang: string; onSourceLangChange: (lang: string) => void; onTargetLangChange: (lang: string) => void; - onTranslationComplete: (path: string) => void; onError: (error: Error) => void; onClearStatus: () => void; } @@ -32,7 +31,6 @@ export function SubtitleTranslator({ targetLang, onSourceLangChange, onTargetLangChange, - onTranslationComplete, onError, onClearStatus, }: Props) { @@ -54,20 +52,16 @@ export function SubtitleTranslator({ onClearStatus(); try { - const { path } = await api.translateSubtitle({ + // The server queues the job; TranslationJobs follows its progress + return await api.translateSubtitle({ serie: show, season: type === 'series' ? season : null, srt_path: subtitlePath, source_lang: sourceLang, target_lang: targetLang, type, + update_plex: updatePlex && !!isPlexConfigured, }); - - if (updatePlex && await PlexService.isConfigured()) { - await PlexService.updateLibrary(); - } - - return path; } catch (caught: unknown) { const error = caught as MutationError; console.log('Translation error:', error); @@ -97,12 +91,8 @@ export function SubtitleTranslator({ throw error; } }, - onSuccess: (path: string) => { - onTranslationComplete(path); - // Wait a bit for DeepL API to update usage stats - setTimeout(() => { - queryClient.invalidateQueries({ queryKey: ['character-count'] }); - }, 2000); // 2-second delay + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['jobs'] }); }, }); @@ -168,7 +158,7 @@ export function SubtitleTranslator({ disabled={isLoading || !subtitlePath || !sourceLang || !targetLang} className="w-full rounded-lg bg-blue-600 px-4 py-3 font-medium text-white transition-colors hover:bg-blue-700 disabled:bg-blue-300" > - {isLoading ? 'Translating...' : 'Translate Subtitle'} + {isLoading ? 'Starting translation...' : 'Translate Subtitle'}
); diff --git a/src/components/TranslationJobs.tsx b/src/components/TranslationJobs.tsx new file mode 100644 index 0000000..97c87fa --- /dev/null +++ b/src/components/TranslationJobs.tsx @@ -0,0 +1,114 @@ +import { useEffect, useRef } from 'react'; +import { useQuery, useQueryClient } from '@tanstack/react-query'; +import { AlertCircle, CheckCircle2, Clock, Loader2 } from 'lucide-react'; +import * as api from '../lib/api'; +import type { TranslationJob } from '../types'; + +const POLL_INTERVAL_MS = 2000; + +const isActive = (job: TranslationJob) => job.status === 'queued' || job.status === 'running'; + +function JobProgress({ job }: { job: TranslationJob }) { + const { done, total } = job.progress; + const percent = total > 0 ? Math.round((done / total) * 100) : 0; + + return ( +
+
+
+
+
+ {job.status === 'queued' + ? 'Waiting in queue...' + : total > 0 + ? `Batch ${done} of ${total} (${percent}%)` + : 'Starting...'} +
+
+ ); +} + +function JobItem({ job }: { job: TranslationJob }) { + const label = `${job.title} · ${job.file} (${job.sourceLang} → ${job.targetLang})`; + + if (isActive(job)) { + const Icon = job.status === 'queued' ? Clock : Loader2; + return ( +
+ +
+
Translating
+
{label}
+ +
+
+ ); + } + + if (job.status === 'done') { + return ( +
+ +
+
Translation Complete!
+
File saved at: {job.path}
+ {job.plex === 'updated' &&
Plex library updated
} + {job.plex === 'failed' &&
{job.plexError}
} +
+
+ ); + } + + return ( +
+ +
+
Translation Failed
+
{label}
+
{job.error?.message}
+ {!!job.error?.apiDetails && ( +
+ Technical details +
+              {JSON.stringify(job.error.apiDetails, null, 2)}
+            
+
+ )} +
+
+ ); +} + +/** + * Lists translation jobs kept by the server, so progress survives page reloads. + * Polls only while a job is queued or running. + */ +export function TranslationJobs() { + const queryClient = useQueryClient(); + const { data: jobs } = useQuery({ + queryKey: ['jobs'], + queryFn: api.getJobs, + refetchInterval: (query) => (query.state.data?.some(isActive) ? POLL_INTERVAL_MS : false), + }); + + // Refresh API usage whenever a job finishes + const activeCount = jobs?.filter(isActive).length ?? 0; + const previousActive = useRef(activeCount); + useEffect(() => { + if (activeCount < previousActive.current) { + queryClient.invalidateQueries({ queryKey: ['character-count'] }); + } + previousActive.current = activeCount; + }, [activeCount, queryClient]); + + if (!jobs?.length) return null; + + return ( +
+ {jobs.slice(0, 5).map(job => )} +
+ ); +} diff --git a/src/components/VideoExtractor.tsx b/src/components/VideoExtractor.tsx index 22f7c9b..fa87a71 100644 --- a/src/components/VideoExtractor.tsx +++ b/src/components/VideoExtractor.tsx @@ -17,7 +17,6 @@ interface Props { targetLang: string; onSourceLangChange: (lang: string) => void; onTargetLangChange: (lang: string) => void; - onTranslationComplete: (path: string) => void; onError: (error: Error) => void; onClearStatus: () => void; } @@ -32,7 +31,6 @@ export function VideoExtractor({ targetLang, onSourceLangChange, onTargetLangChange, - onTranslationComplete, onError, onClearStatus, }: Props) { @@ -79,21 +77,16 @@ export function VideoExtractor({ // Get just the filename from the path const filename = extractedPath.split('/').pop(); - // Then translate them - const { path: translatedPath } = await api.translateSubtitle({ + // Then queue the translation; TranslationJobs follows its progress + return await api.translateSubtitle({ serie: show, season: type === 'series' ? season : null, srt_path: filename!, source_lang: sourceLang, target_lang: targetLang, type, + update_plex: updatePlex && !!isPlexConfigured, }); - - if (updatePlex && await PlexService.isConfigured()) { - await PlexService.updateLibrary(); - } - - return translatedPath; } catch (caught: unknown) { const error = caught as MutationError; console.log('Extraction error:', error); @@ -108,12 +101,8 @@ export function VideoExtractor({ throw error; } }, - onSuccess: (path: string) => { // Added type annotation to path - onTranslationComplete(path); - // Wait a bit for DeepL API to update usage stats - setTimeout(() => { - queryClient.invalidateQueries({ queryKey: ['character-count'] }); - }, 2000); // 2-second delay + onSuccess: () => { + queryClient.invalidateQueries({ queryKey: ['jobs'] }); }, }); diff --git a/src/lib/api.ts b/src/lib/api.ts index 2a7377d..51ecd99 100644 --- a/src/lib/api.ts +++ b/src/lib/api.ts @@ -1,5 +1,5 @@ import axios, { AxiosResponse, AxiosError } from 'axios'; -import type { CharacterCount, Show, Movie, SubtitleFile, VideoFile, ApiErrorResponse } from '../types'; +import type { CharacterCount, Show, Movie, SubtitleFile, VideoFile, ApiErrorResponse, TranslationJob } from '../types'; const api = axios.create({ baseURL: '/api', @@ -96,6 +96,10 @@ export const extractSubtitles = async (params: { } }; +/** + * Queues a translation on the server and returns the job right away. + * Progress is followed with getJobs(). + */ export const translateSubtitle = async (params: { serie: string; season?: string | null; @@ -103,15 +107,15 @@ export const translateSubtitle = async (params: { source_lang: string; target_lang: string; type: 'series' | 'movies'; -}): Promise<{ path: string }> => { - try { - const { data } = await api.post('/translate_subtitle', params); - return data; - } catch (error) { - console.error('Translation error:', error); - // Re-throw the error for handling in the UI components - throw error; - } + update_plex: boolean; +}): Promise => { + const { data } = await api.post('/translate_subtitle', params); + return data; +}; + +export const getJobs = async (): Promise => { + const { data } = await api.get('/jobs'); + return data; }; export async function isPlexConfigured(): Promise { diff --git a/src/types/index.ts b/src/types/index.ts index ffc8606..939df3b 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -21,8 +21,30 @@ export interface VideoFile { } export interface CharacterCount { - character_count: number; - character_limit: number; + provider?: 'deepl' | 'llm'; + character_count?: number; + character_limit?: number; + model?: string | null; + prompt_tokens?: number; + completion_tokens?: number; +} + +export interface TranslationJob { + id: string; + status: 'queued' | 'running' | 'done' | 'error'; + file: string; + title: string; + sourceLang: string; + targetLang: string; + updatePlex: boolean; + progress: { done: number; total: number }; + createdAt: string; + startedAt?: string; + finishedAt?: string; + path?: string; + plex?: 'updated' | 'failed' | 'skipped'; + plexError?: string; + error?: { message: string; status: number; apiDetails: unknown }; } export interface Language { From 422b87fe3af2baf56b1b23f2d081a00c6422ee88 Mon Sep 17 00:00:00 2001 From: Giovanny Aranda Date: Fri, 23 Oct 2026 15:56:12 +0200 Subject: [PATCH 2/6] fix: prevent duplicate translation jobs for the same file and language The server rejects a new job with 409 when the same subtitle file and target language is already queued or running, and the translate button is disabled in that case. Other files and languages can still be queued. --- server/routes/subtitle.js | 21 +++++++++++++-------- server/services/jobs.js | 15 ++++++++++++++- src/components/SubtitleTranslator.tsx | 19 +++++++++++++++++-- src/types/index.ts | 1 + 4 files changed, 45 insertions(+), 11 deletions(-) diff --git a/server/routes/subtitle.js b/server/routes/subtitle.js index d1e8a04..7df353d 100644 --- a/server/routes/subtitle.js +++ b/server/routes/subtitle.js @@ -30,14 +30,19 @@ router.post('/translate_subtitle', (req, res) => { } // Translation can take minutes with an LLM, so it runs as a background job - const job = createTranslationJob({ - subtitlePath, - sourceLang: source_lang, - targetLang: target_lang, - title: serie, - updatePlex: update_plex, - }); - res.status(202).json(job); + try { + const job = createTranslationJob({ + subtitlePath, + sourceLang: source_lang, + targetLang: target_lang, + title: serie, + season: type === 'series' ? season : null, + updatePlex: update_plex, + }); + res.status(202).json(job); + } catch (error) { + res.status(error.status || 500).json({ message: error.message }); + } }); router.get('/jobs', (req, res) => { diff --git a/server/services/jobs.js b/server/services/jobs.js index bf434c0..e2172c4 100644 --- a/server/services/jobs.js +++ b/server/services/jobs.js @@ -70,13 +70,26 @@ async function processQueue() { /** * Queues a subtitle translation. Jobs run one at a time. + * Throws a 409 error if the same file and target language is already queued or running. */ -export function createTranslationJob({ subtitlePath, sourceLang, targetLang, title, updatePlex }) { +export function createTranslationJob({ subtitlePath, sourceLang, targetLang, title, season, updatePlex }) { + const duplicate = [...jobs.values()].some(job => + (job.status === 'queued' || job.status === 'running') + && job.subtitlePath === subtitlePath + && job.targetLang === targetLang + ); + if (duplicate) { + const error = new Error(`${basename(subtitlePath)} is already being translated to ${targetLang}`); + error.status = 409; + throw error; + } + const job = { id: randomUUID(), status: 'queued', file: basename(subtitlePath), title, + season: season || null, sourceLang, targetLang, updatePlex: !!updatePlex, diff --git a/src/components/SubtitleTranslator.tsx b/src/components/SubtitleTranslator.tsx index 36d33b6..88da3ae 100644 --- a/src/components/SubtitleTranslator.tsx +++ b/src/components/SubtitleTranslator.tsx @@ -47,6 +47,19 @@ export function SubtitleTranslator({ queryKey: ['plexStatus'], queryFn: () => PlexService.isConfigured(), }); + // Shares the cache polled by TranslationJobs + const { data: jobs } = useQuery({ + queryKey: ['jobs'], + queryFn: api.getJobs, + }); + const isAlreadyTranslating = !!jobs?.some(job => + (job.status === 'queued' || job.status === 'running') + && job.title === show + && job.season === (type === 'series' ? season : null) + && job.file === subtitlePath + && job.targetLang === targetLang + ); + const translateMutation = useMutation({ mutationFn: async () => { onClearStatus(); @@ -155,10 +168,12 @@ export function SubtitleTranslator({
); diff --git a/src/types/index.ts b/src/types/index.ts index 939df3b..ce623a4 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -34,6 +34,7 @@ export interface TranslationJob { status: 'queued' | 'running' | 'done' | 'error'; file: string; title: string; + season: string | null; sourceLang: string; targetLang: string; updatePlex: boolean; From 79ecd7be709654d507128163490f9915a4b3d397 Mon Sep 17 00:00:00 2001 From: Giovanny Aranda Date: Fri, 23 Oct 2026 16:10:22 +0200 Subject: [PATCH 3/6] feat: add LLM fallback models and resumable translation jobs - LLM_FALLBACK_MODELS lists models tried in order when LLM_MODEL keeps failing. Models with a fallback fail over after 2 attempts and are skipped for 5 minutes; auth errors do not trigger a fallback. - Jobs keep the translations of finished batches. A failed job can be resumed with POST /jobs/:id/retry, which skips completed batches for both DeepL and LLM providers. - When one LLM batch fails, workers stop taking new batches and wait for in-flight ones, so a retry never overlaps a run still in progress. - The UI shows where a job stopped and a Resume translation button. --- README.md | 13 +++++ docker-compose.yml | 1 + server/routes/subtitle.js | 10 +++- server/services/jobs.js | 67 +++++++++++++++++++---- server/services/llm.js | 88 +++++++++++++++++++++++------- server/services/translator.js | 29 ++++++++-- src/components/TranslationJobs.tsx | 30 +++++++++- src/lib/api.ts | 6 ++ src/types/index.ts | 2 + 9 files changed, 205 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 6337b3f..70ec3b9 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,7 @@ The application offers optional integration with a Plex server, allowing you to | `LLM_BASE_URL` | OpenAI-compatible API base URL (default `https://api.openai.com/v1`) | Optional | | `LLM_API_KEY` | API key for the LLM endpoint | Yes, with `llm` (except local servers) | | `LLM_MODEL` | Model name, e.g. `gpt-4.1`, `anthropic/claude-sonnet-5-5` | Yes, with `llm` | +| `LLM_FALLBACK_MODELS` | Comma-separated models tried in order when `LLM_MODEL` keeps failing | Optional | | `LLM_BATCH_SIZE` | Subtitles per request (default `25`) | Optional | | `LLM_CONTEXT_SIZE` | Previous lines sent as context (default `5`) | Optional | | `LLM_CONCURRENCY` | Parallel requests (default `3`) | Optional | @@ -98,6 +99,18 @@ and numbering are never altered. | LiteLLM proxy | `http://litellm:4000/v1` | any model configured in LiteLLM | | Ollama | `http://ollama:11434/v1` | `qwen2.5:14b` | +### Fallback models and resuming + +Free models often fail with rate limits or provider errors. Set `LLM_FALLBACK_MODELS` to a +comma-separated list of models to try in order; a model that fails over is skipped for the +next 5 minutes. Translations run as background jobs, and if a job still fails, the +**Resume translation** button continues from the last finished batch instead of starting over. + +```env +LLM_MODEL=google/gemma-4-26b-a4b-it:free +LLM_FALLBACK_MODELS=nvidia/nemotron-3.5-super-vl:free,dots-studio/dots-3-note-preview:free +``` + ### Custom system prompt The bundled prompt lives in [`server/prompts/llm-system-prompt.txt`](server/prompts/llm-system-prompt.txt). diff --git a/docker-compose.yml b/docker-compose.yml index eaac548..f615a03 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -12,6 +12,7 @@ services: - LLM_BASE_URL=${LLM_BASE_URL} - LLM_API_KEY=${LLM_API_KEY} - LLM_MODEL=${LLM_MODEL} + - LLM_FALLBACK_MODELS=${LLM_FALLBACK_MODELS} - PLEX_HOST=${PLEX_HOST} - PLEX_PORT=${PLEX_PORT} - PLEX_TOKEN=${PLEX_TOKEN} diff --git a/server/routes/subtitle.js b/server/routes/subtitle.js index 7df353d..a2005c9 100644 --- a/server/routes/subtitle.js +++ b/server/routes/subtitle.js @@ -2,7 +2,7 @@ import { Router } from 'express'; import { join } from 'path'; import { existsSync } from 'fs'; import { getConfigError } from '../services/translator.js'; -import { createTranslationJob, getJob, listJobs } from '../services/jobs.js'; +import { createTranslationJob, getJob, listJobs, retryJob } from '../services/jobs.js'; import { extractSubtitles } from '../services/ffmpeg.js'; import { DATA_DIR, MOVIES_DIR } from '../utils/paths.js'; const router = Router(); @@ -49,6 +49,14 @@ router.get('/jobs', (req, res) => { res.json(listJobs()); }); +router.post('/jobs/:id/retry', (req, res) => { + try { + res.status(202).json(retryJob(req.params.id)); + } catch (error) { + res.status(error.status || 500).json({ message: error.message }); + } +}); + router.get('/jobs/:id', (req, res) => { const job = getJob(req.params.id); if (!job) { diff --git a/server/services/jobs.js b/server/services/jobs.js index e2172c4..5f9e44e 100644 --- a/server/services/jobs.js +++ b/server/services/jobs.js @@ -11,12 +11,30 @@ const queue = []; let running = false; function toPublic(job) { - const { subtitlePath: _subtitlePath, ...rest } = job; + const { subtitlePath: _subtitlePath, partial: _partial, ...rest } = job; return rest; } +function isActive(job) { + return job.status === 'queued' || job.status === 'running'; +} + +function assertNotDuplicate(subtitlePath, targetLang, exceptId) { + const duplicate = [...jobs.values()].some(job => + job.id !== exceptId + && isActive(job) + && job.subtitlePath === subtitlePath + && job.targetLang === targetLang + ); + if (duplicate) { + const error = new Error(`${basename(subtitlePath)} is already being translated to ${targetLang}`); + error.status = 409; + throw error; + } +} + function pruneFinished() { - const finished = [...jobs.values()].filter(job => job.status === 'done' || job.status === 'error'); + const finished = [...jobs.values()].filter(job => !isActive(job)); for (const job of finished.slice(0, Math.max(0, finished.length - MAX_FINISHED_JOBS))) { jobs.delete(job.id); } @@ -28,6 +46,7 @@ async function runJob(job) { try { job.path = await translateSRT(job.subtitlePath, job.sourceLang, job.targetLang, { title: job.title, + partial: job.partial, onProgress: (done, total) => { job.progress = { done, total }; }, @@ -45,6 +64,7 @@ async function runJob(job) { job.plex = 'skipped'; } job.status = 'done'; + job.partial = []; } catch (error) { console.error(`Translation job ${job.id} failed:`, error.message); job.status = 'error'; @@ -73,16 +93,7 @@ async function processQueue() { * Throws a 409 error if the same file and target language is already queued or running. */ export function createTranslationJob({ subtitlePath, sourceLang, targetLang, title, season, updatePlex }) { - const duplicate = [...jobs.values()].some(job => - (job.status === 'queued' || job.status === 'running') - && job.subtitlePath === subtitlePath - && job.targetLang === targetLang - ); - if (duplicate) { - const error = new Error(`${basename(subtitlePath)} is already being translated to ${targetLang}`); - error.status = 409; - throw error; - } + assertNotDuplicate(subtitlePath, targetLang); const job = { id: randomUUID(), @@ -94,8 +105,11 @@ export function createTranslationJob({ subtitlePath, sourceLang, targetLang, tit targetLang, updatePlex: !!updatePlex, progress: { done: 0, total: 0 }, + attempts: 1, createdAt: new Date().toISOString(), subtitlePath, + // Translations finished so far, kept so a retry resumes instead of restarting + partial: [], }; jobs.set(job.id, job); queue.push(job); @@ -103,6 +117,35 @@ export function createTranslationJob({ subtitlePath, sourceLang, targetLang, tit return toPublic(job); } +/** + * Requeues a failed job. Batches translated before the failure are kept. + */ +export function retryJob(id) { + const job = jobs.get(id); + if (!job) { + const error = new Error('Job not found'); + error.status = 404; + throw error; + } + if (job.status !== 'error') { + const error = new Error('Only failed jobs can be retried'); + error.status = 409; + throw error; + } + assertNotDuplicate(job.subtitlePath, job.targetLang, job.id); + + job.status = 'queued'; + job.attempts += 1; + delete job.error; + delete job.finishedAt; + // Move it to the end so it shows up as the most recent job + jobs.delete(job.id); + jobs.set(job.id, job); + queue.push(job); + processQueue(); + return toPublic(job); +} + export function getJob(id) { const job = jobs.get(id); return job ? toPublic(job) : null; diff --git a/server/services/llm.js b/server/services/llm.js index 9098717..f58f91b 100644 --- a/server/services/llm.js +++ b/server/services/llm.js @@ -14,8 +14,12 @@ const CONCURRENCY = parseInt(process.env.LLM_CONCURRENCY || '3', 10); const TEMPERATURE = parseFloat(process.env.LLM_TEMPERATURE || '0.2'); const JSON_MODE = process.env.LLM_JSON_MODE !== 'false'; const REQUEST_TIMEOUT = 180000; // 3 minutes per request +const FALLBACK_COOLDOWN_MS = 5 * 60 * 1000; // skip a failing model for 5 minutes const MAX_HTTP_RETRIES = parseInt(process.env.LLM_MAX_RETRIES || '5', 10); +// Models that recently failed over, mapped to the time they can be used again +const cooldownUntil = new Map(); + // Tokens consumed since the server started (shown in the UI) const usage = { prompt_tokens: 0, completion_tokens: 0 }; @@ -33,6 +37,7 @@ export function getLLMUsage() { return { provider: 'llm', model: process.env.LLM_MODEL || null, + fallback_models: getModels().slice(1), prompt_tokens: usage.prompt_tokens, completion_tokens: usage.completion_tokens, }; @@ -63,9 +68,17 @@ function loadSystemPrompt(sourceLang, targetLang) { .replaceAll('{{TARGET_LANG}}', languageName(targetLang)); } -async function chatCompletion(systemPrompt, userContent) { +function getModels() { + const fallbacks = (process.env.LLM_FALLBACK_MODELS || '') + .split(',') + .map(model => model.trim()) + .filter(Boolean); + return [process.env.LLM_MODEL, ...fallbacks]; +} + +async function requestCompletion(model, systemPrompt, userContent, maxRetries) { const body = { - model: process.env.LLM_MODEL, + model, temperature: TEMPERATURE, messages: [ { role: 'system', content: systemPrompt }, @@ -95,10 +108,10 @@ async function chatCompletion(systemPrompt, userContent) { } catch (error) { const status = error.response?.status; const retryable = !status || status === 429 || status >= 500; - if (!retryable || attempt >= MAX_HTTP_RETRIES) { + if (!retryable || attempt >= maxRetries) { if (error.response) { const apiMessage = error.response.data?.error?.message || `API Error (${status})`; - const enhanced = new Error(`LLM API error: ${apiMessage}`); + const enhanced = new Error(`LLM API error (${model}): ${apiMessage}`); enhanced.status = status; enhanced.apiDetails = error.response.data; throw enhanced; @@ -111,12 +124,35 @@ async function chatCompletion(systemPrompt, userContent) { // Honor Retry-After when present, otherwise exponential backoff capped at 30s const retryAfter = parseInt(error.response?.headers?.['retry-after'], 10); const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(2000 * 2 ** (attempt - 1), 30000); - console.warn(`LLM request failed (${status || error.code}), retrying in ${delay / 1000}s...`); + console.warn(`LLM request to ${model} failed (${status || error.code}), retrying in ${delay / 1000}s...`); await new Promise((resolve) => setTimeout(resolve, delay)); } } } +/** + * Sends a chat request, falling back to LLM_FALLBACK_MODELS in order when a + * model keeps failing. Models with a fallback after them fail over quickly, + * and a model that failed over is skipped for a while. + */ +async function chatCompletion(systemPrompt, userContent) { + const models = getModels(); + for (let i = 0; ; i++) { + const isLast = i === models.length - 1; + if (!isLast && cooldownUntil.get(models[i]) > Date.now()) continue; + try { + const content = await requestCompletion(models[i], systemPrompt, userContent, isLast ? MAX_HTTP_RETRIES : 2); + cooldownUntil.delete(models[i]); + return content; + } catch (error) { + // Auth errors would fail the same way on every model + if (isLast || error.status === 401 || error.status === 403) throw error; + cooldownUntil.set(models[i], Date.now() + FALLBACK_COOLDOWN_MS); + console.warn(`${error.message}; falling back to ${models[i + 1]} for the next 5 minutes`); + } + } +} + function parseItems(content) { // Tolerate models that wrap the JSON in code fences or add stray text const start = content.indexOf('{'); @@ -180,11 +216,14 @@ async function translateBatch(systemPrompt, entries, context, title) { * @param {string[]} texts Texts to translate * @param {string} sourceLang Source language code * @param {string} targetLang Target language code - * @param {{title?: string, onProgress?: (done: number, total: number) => void}} options - * Extra context for the model and a batch progress callback + * @param {object} options + * @param {string} [options.title] Title of the work, as context for the model + * @param {(done: number, total: number) => void} [options.onProgress] Batch progress callback + * @param {Array} [options.partial] Translations from a previous + * failed run; filled in as batches complete so a retry skips finished batches * @returns {Promise} Translations in the same order */ -export async function translateTextsLLM(texts, sourceLang, targetLang, { title, onProgress } = {}) { +export async function translateTextsLLM(texts, sourceLang, targetLang, { title, onProgress, partial = [] } = {}) { const systemPrompt = loadSystemPrompt(sourceLang, targetLang); const entries = texts.map((t, i) => ({ i, t })); @@ -196,21 +235,32 @@ export async function translateTextsLLM(texts, sourceLang, targetLang, { title, context: entries.slice(Math.max(0, start - CONTEXT_SIZE), start), }); } - console.log(`Translating ${texts.length} texts with ${process.env.LLM_MODEL} in ${batches.length} batch(es)`); - const results = new Array(batches.length); + const isDone = (batch) => batch.entries.every(({ i }) => partial[i] !== undefined); + const pending = batches.filter(batch => !isDone(batch)); + let done = batches.length - pending.length; + console.log(`Translating ${texts.length} texts with ${getModels().join(' > ')} in ${batches.length} batch(es)` + + (done > 0 ? `, resuming with ${done} already done` : '')); + onProgress?.(done, batches.length); + + // On the first failure, stop taking new batches and let in-flight ones finish + let failure = null; let next = 0; - let done = 0; - onProgress?.(0, batches.length); const worker = async () => { - while (next < batches.length) { - const index = next++; - results[index] = await translateBatch(systemPrompt, batches[index].entries, batches[index].context, title); - console.log(`LLM batch ${++done}/${batches.length} done`); - onProgress?.(done, batches.length); + while (!failure && next < pending.length) { + const batch = pending[next++]; + try { + const translated = await translateBatch(systemPrompt, batch.entries, batch.context, title); + batch.entries.forEach(({ i }, k) => { partial[i] = translated[k]; }); + console.log(`LLM batch ${++done}/${batches.length} done`); + onProgress?.(done, batches.length); + } catch (error) { + failure ??= error; + } } }; - await Promise.all(Array.from({ length: Math.min(CONCURRENCY, batches.length) }, worker)); + await Promise.all(Array.from({ length: Math.min(CONCURRENCY, pending.length) }, worker)); + if (failure) throw failure; - return results.flat(); + return texts.map((_, i) => partial[i]); } diff --git a/server/services/translator.js b/server/services/translator.js index 057ac4a..5718a3d 100644 --- a/server/services/translator.js +++ b/server/services/translator.js @@ -24,19 +24,27 @@ export async function getUsage() { return { provider: 'deepl', ...(await getUsageStats()) }; } -async function translateWithDeepL(texts, sourceLang, targetLang, { onProgress } = {}) { +async function translateWithDeepL(texts, sourceLang, targetLang, { onProgress, partial = [] } = {}) { // Replace newlines with space so DeepL receives each subtitle as a single // sentence with full context, instead of treating each line independently. const normalized = texts.map(text => text.replace(/\n/g, ' ')); const batches = buildTextBatches(normalized); console.log(`Sending ${normalized.length} non-empty texts to DeepL in ${batches.length} batch(es)`); - const translatedTexts = []; onProgress?.(0, batches.length); + let offset = 0; for (let i = 0; i < batches.length; i++) { + const start = offset; + offset += batches[i].length; + // Skip batches already translated by a previous failed run + if (batches[i].every((_, k) => partial[start + k] !== undefined)) { + onProgress?.(i + 1, batches.length); + continue; + } console.log(`Translating batch ${i + 1}/${batches.length} (${batches[i].length} texts)...`); try { - translatedTexts.push(...await translateTexts(batches[i], sourceLang, targetLang)); + const results = await translateTexts(batches[i], sourceLang, targetLang); + results.forEach((text, k) => { partial[start + k] = text; }); onProgress?.(i + 1, batches.length); } catch (error) { console.error(`Error translating batch ${i + 1}:`, error.message); @@ -52,7 +60,7 @@ async function translateWithDeepL(texts, sourceLang, targetLang, { onProgress } throw error; } } - return translatedTexts; + return texts.map((_, i) => partial[i]); } /** @@ -61,8 +69,11 @@ async function translateWithDeepL(texts, sourceLang, targetLang, { onProgress } * @param {string} filePath Path to the SRT file * @param {string} sourceLang Source language * @param {string} targetLang Target language - * @param {{title?: string, onProgress?: (done: number, total: number) => void}} options - * Extra context for the LLM provider and a batch progress callback + * @param {object} options + * @param {string} [options.title] Title of the work, as context for the LLM provider + * @param {(done: number, total: number) => void} [options.onProgress] Batch progress callback + * @param {Array} [options.partial] Translations kept between runs + * so a retry resumes where the previous run failed * @returns {Promise} Path to the translated file */ export async function translateSRT(filePath, sourceLang, targetLang, options = {}) { @@ -79,6 +90,12 @@ export async function translateSRT(filePath, sourceLang, targetLang, options = { } const texts = toTranslate.map(item => item.text); + // Discard saved progress if the file changed since the failed run + if (options.partial && options.partial.length !== texts.length) { + options.partial.length = 0; + options.partial.length = texts.length; + } + const translatedTexts = provider === 'llm' ? await translateTextsLLM(texts, sourceLang, targetLang, options) : await translateWithDeepL(texts, sourceLang, targetLang, options); diff --git a/src/components/TranslationJobs.tsx b/src/components/TranslationJobs.tsx index 97c87fa..0ef6011 100644 --- a/src/components/TranslationJobs.tsx +++ b/src/components/TranslationJobs.tsx @@ -1,6 +1,6 @@ import { useEffect, useRef } from 'react'; -import { useQuery, useQueryClient } from '@tanstack/react-query'; -import { AlertCircle, CheckCircle2, Clock, Loader2 } from 'lucide-react'; +import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'; +import { AlertCircle, CheckCircle2, Clock, Loader2, RotateCw } from 'lucide-react'; import * as api from '../lib/api'; import type { TranslationJob } from '../types'; @@ -32,6 +32,11 @@ function JobProgress({ job }: { job: TranslationJob }) { } function JobItem({ job }: { job: TranslationJob }) { + const queryClient = useQueryClient(); + const retryMutation = useMutation({ + mutationFn: () => api.retryJob(job.id), + onSettled: () => queryClient.invalidateQueries({ queryKey: ['jobs'] }), + }); const label = `${job.title} · ${job.file} (${job.sourceLang} → ${job.targetLang})`; if (isActive(job)) { @@ -40,7 +45,9 @@ function JobItem({ job }: { job: TranslationJob }) {
-
Translating
+
+ Translating{job.attempts > 1 && ` (attempt ${job.attempts})`} +
{label}
@@ -69,6 +76,23 @@ function JobItem({ job }: { job: TranslationJob }) {
Translation Failed
{label}
{job.error?.message}
+ {job.progress.total > 0 && ( +
+ Stopped at batch {job.progress.done} of {job.progress.total} + {job.progress.done > 0 && ' · finished batches are kept and will not be translated again'} +
+ )} + + {retryMutation.isError && ( +
{(retryMutation.error as Error).message}
+ )} {!!job.error?.apiDetails && (
Technical details diff --git a/src/lib/api.ts b/src/lib/api.ts index 51ecd99..34faaa0 100644 --- a/src/lib/api.ts +++ b/src/lib/api.ts @@ -113,6 +113,12 @@ export const translateSubtitle = async (params: { return data; }; +/** Requeues a failed job; batches finished before the failure are kept. */ +export const retryJob = async (id: string): Promise => { + const { data } = await api.post(`/jobs/${id}/retry`); + return data; +}; + export const getJobs = async (): Promise => { const { data } = await api.get('/jobs'); return data; diff --git a/src/types/index.ts b/src/types/index.ts index ce623a4..1ac52fd 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -25,6 +25,7 @@ export interface CharacterCount { character_count?: number; character_limit?: number; model?: string | null; + fallback_models?: string[]; prompt_tokens?: number; completion_tokens?: number; } @@ -39,6 +40,7 @@ export interface TranslationJob { targetLang: string; updatePlex: boolean; progress: { done: number; total: number }; + attempts: number; createdAt: string; startedAt?: string; finishedAt?: string; From acb34624f1461bf76e8821e7729fde2d62d19a7b Mon Sep 17 00:00:00 2001 From: Giovanny Aranda Date: Sun, 25 Oct 2026 12:20:29 +0100 Subject: [PATCH 4/6] fix: delay usage refresh after a job finishes so DeepL stats are up to date --- src/components/TranslationJobs.tsx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/src/components/TranslationJobs.tsx b/src/components/TranslationJobs.tsx index 0ef6011..e4dbda6 100644 --- a/src/components/TranslationJobs.tsx +++ b/src/components/TranslationJobs.tsx @@ -122,10 +122,14 @@ export function TranslationJobs() { const activeCount = jobs?.filter(isActive).length ?? 0; const previousActive = useRef(activeCount); useEffect(() => { - if (activeCount < previousActive.current) { - queryClient.invalidateQueries({ queryKey: ['character-count'] }); - } + const finished = activeCount < previousActive.current; previousActive.current = activeCount; + if (!finished) return; + // Wait a bit for DeepL API to update usage stats + const timer = setTimeout(() => { + queryClient.invalidateQueries({ queryKey: ['character-count'] }); + }, 2000); + return () => clearTimeout(timer); }, [activeCount, queryClient]); if (!jobs?.length) return null; From bc1c37acb0ca3f7154e927a1003b27f5d57866bf Mon Sep 17 00:00:00 2001 From: Giovanny Aranda Date: Sun, 25 Oct 2026 12:49:02 +0100 Subject: [PATCH 5/6] fix: address PR review feedback - Validate numeric LLM env vars and fall back to defaults; LLM_BATCH_SIZE=0 previously looped forever and LLM_CONCURRENCY=0 produced empty output. - Reject paths that resolve outside DATA_DIR/MOVIES_DIR, invalid language codes (they end up in the output file name), non-.srt files and unknown types in translate_subtitle and extract_subtitles. - Stop returning error stacks from extract_subtitles. - Clear the previous attempt's timings, path and Plex state on retry. - Prune completed jobs before failed ones so resume progress is not lost. - Keep the job queue running if an unexpected error escapes a job. - Document the error status contract in translateBatch and the fallback retry budget and LLM_JSON_MODE in the README. --- README.md | 8 ++++-- server/routes/subtitle.js | 59 +++++++++++++++++++++++++++++---------- server/services/jobs.js | 38 ++++++++++++++++++++----- server/services/llm.js | 31 ++++++++++++++++---- 4 files changed, 107 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index 70ec3b9..44a9ef2 100644 --- a/README.md +++ b/README.md @@ -102,8 +102,12 @@ and numbering are never altered. ### Fallback models and resuming Free models often fail with rate limits or provider errors. Set `LLM_FALLBACK_MODELS` to a -comma-separated list of models to try in order; a model that fails over is skipped for the -next 5 minutes. Translations run as background jobs, and if a job still fails, the +comma-separated list of models to try in order. When fallbacks are configured, each model +before the last one gets only 2 attempts (so a rate-limited free model hands over quickly), +the last one gets `LLM_MAX_RETRIES`, and a model that fails over is skipped for the next +5 minutes. Any error except an authentication error (401/403) triggers a fallback, including +a 400 from a model that rejects `response_format`; set `LLM_JSON_MODE=false` if your models +do not support JSON mode. Translations run as background jobs, and if a job still fails, the **Resume translation** button continues from the last finished batch instead of starting over. ```env diff --git a/server/routes/subtitle.js b/server/routes/subtitle.js index a2005c9..48a86d1 100644 --- a/server/routes/subtitle.js +++ b/server/routes/subtitle.js @@ -1,5 +1,5 @@ import { Router } from 'express'; -import { join } from 'path'; +import { resolve, sep } from 'path'; import { existsSync } from 'fs'; import { getConfigError } from '../services/translator.js'; import { createTranslationJob, getJob, listJobs, retryJob } from '../services/jobs.js'; @@ -7,6 +7,19 @@ import { extractSubtitles } from '../services/ffmpeg.js'; import { DATA_DIR, MOVIES_DIR } from '../utils/paths.js'; const router = Router(); +const LANG_CODE = /^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$/; + +/** + * Joins path segments under a base directory and rejects anything that + * resolves outside of it (e.g. "../" in user-provided names). + * @returns {string|null} The resolved path, or null if it escapes the base + */ +function resolveInside(base, ...segments) { + const root = resolve(base); + const target = resolve(root, ...segments.map(String)); + return target.startsWith(root + sep) ? target : null; +} + router.post('/translate_subtitle', (req, res) => { const { serie, season, srt_path, source_lang, target_lang, type, update_plex } = req.body; @@ -17,14 +30,28 @@ router.post('/translate_subtitle', (req, res) => { return res.status(400).json({ message: 'Missing parameters' }); } + else if (type !== 'series' && type !== 'movies') { + return res.status(400).json({ message: 'Invalid type' }); + } + // Language codes end up in the output file name, so keep them strict + if (!LANG_CODE.test(source_lang) || !LANG_CODE.test(target_lang)) { + return res.status(400).json({ message: 'Invalid language code' }); + } + if (!String(srt_path).toLowerCase().endsWith('.srt')) { + return res.status(400).json({ message: 'Only .srt files can be translated' }); + } + const configError = getConfigError(); if (configError) { return res.status(400).json({ message: configError }); } const subtitlePath = type === 'series' - ? join(DATA_DIR, serie, season, srt_path) - : join(MOVIES_DIR, serie, srt_path); + ? resolveInside(DATA_DIR, serie, season, srt_path) + : resolveInside(MOVIES_DIR, serie, srt_path); + if (!subtitlePath) { + return res.status(400).json({ message: 'Invalid subtitle path' }); + } if (!existsSync(subtitlePath)) { return res.status(404).json({ message: `Subtitle file not found: ${srt_path}` }); } @@ -76,15 +103,20 @@ router.post('/extract_subtitles', async (req, res) => { return res.status(400).json({ error: 'Missing parameters' }); } - let videoPath, outputPath; - if (type === 'series') { - videoPath = join(DATA_DIR, serie, season, video_file); - const videoFileName = video_file.substring(0, video_file.lastIndexOf('.')); - outputPath = join(DATA_DIR, serie, season, `${videoFileName}.${source_lang.toLowerCase()}.srt`); - } else { - videoPath = join(MOVIES_DIR, serie, video_file); - const videoFileName = video_file.substring(0, video_file.lastIndexOf('.')); - outputPath = join(MOVIES_DIR, serie, `${videoFileName}.${source_lang.toLowerCase()}.srt`); + else if (type !== 'series' && type !== 'movies') { + return res.status(400).json({ message: 'Invalid type' }); + } + if (!LANG_CODE.test(source_lang)) { + return res.status(400).json({ message: 'Invalid language code' }); + } + + const videoFileName = video_file.substring(0, video_file.lastIndexOf('.')); + const outputName = `${videoFileName}.${source_lang.toLowerCase()}.srt`; + const [videoPath, outputPath] = type === 'series' + ? [resolveInside(DATA_DIR, serie, season, video_file), resolveInside(DATA_DIR, serie, season, outputName)] + : [resolveInside(MOVIES_DIR, serie, video_file), resolveInside(MOVIES_DIR, serie, outputName)]; + if (!videoPath || !outputPath) { + return res.status(400).json({ message: 'Invalid video path' }); } await extractSubtitles(videoPath, outputPath); @@ -107,8 +139,7 @@ router.post('/extract_subtitles', async (req, res) => { res.status(statusCode).json({ message: userMessage, - originalError: error.toString(), - stack: error.stack + originalError: error.toString() }); } }); diff --git a/server/services/jobs.js b/server/services/jobs.js index 5f9e44e..7491996 100644 --- a/server/services/jobs.js +++ b/server/services/jobs.js @@ -4,6 +4,7 @@ import { translateSRT } from './translator.js'; import { isConfigured as isPlexConfigured, updateLibrary } from './plexService.js'; const MAX_FINISHED_JOBS = 20; +const MAX_FAILED_JOBS = 50; // failed jobs keep resume progress, so they are pruned last // In-memory job store: survives page reloads, not server restarts const jobs = new Map(); @@ -33,13 +34,24 @@ function assertNotDuplicate(subtitlePath, targetLang, exceptId) { } } -function pruneFinished() { - const finished = [...jobs.values()].filter(job => !isActive(job)); - for (const job of finished.slice(0, Math.max(0, finished.length - MAX_FINISHED_JOBS))) { +function pruneOldest(list, keep) { + for (const job of list.slice(0, Math.max(0, list.length - keep))) { jobs.delete(job.id); } } +/** + * Drops the oldest finished jobs. Completed jobs go first; failed jobs hold + * resumable progress and get a separate, larger limit. + */ +function pruneFinished() { + const all = [...jobs.values()]; + const done = all.filter(job => job.status === 'done'); + const failed = all.filter(job => job.status === 'error'); + pruneOldest(done, Math.max(0, MAX_FINISHED_JOBS - failed.length)); + pruneOldest(failed, MAX_FAILED_JOBS); +} + async function runJob(job) { job.status = 'running'; job.startedAt = new Date().toISOString(); @@ -81,11 +93,18 @@ async function runJob(job) { async function processQueue() { if (running) return; running = true; - while (queue.length > 0) { - await runJob(queue.shift()); - pruneFinished(); + try { + while (queue.length > 0) { + await runJob(queue.shift()); + pruneFinished(); + } + } catch (error) { + // processQueue is not awaited, so log instead of leaving an unhandled rejection + console.error('Translation queue stopped unexpectedly:', error); + } finally { + // Never leave the queue stuck if something unexpected throws + running = false; } - running = false; } /** @@ -136,8 +155,13 @@ export function retryJob(id) { job.status = 'queued'; job.attempts += 1; + // Clear state from the previous attempt; progress is kept in job.partial delete job.error; + delete job.startedAt; delete job.finishedAt; + delete job.path; + delete job.plex; + delete job.plexError; // Move it to the end so it shows up as the most recent job jobs.delete(job.id); jobs.set(job.id, job); diff --git a/server/services/llm.js b/server/services/llm.js index f58f91b..7b55b72 100644 --- a/server/services/llm.js +++ b/server/services/llm.js @@ -8,14 +8,30 @@ const DEFAULT_PROMPT_PATH = join(__dirname, '..', 'prompts', 'llm-system-prompt. const CUSTOM_PROMPT_PATH = process.env.LLM_PROMPT_FILE || '/config/llm-system-prompt.txt'; const BASE_URL = (process.env.LLM_BASE_URL || 'https://api.openai.com/v1').replace(/\/+$/, ''); -const BATCH_SIZE = parseInt(process.env.LLM_BATCH_SIZE || '25', 10); -const CONTEXT_SIZE = parseInt(process.env.LLM_CONTEXT_SIZE || '5', 10); -const CONCURRENCY = parseInt(process.env.LLM_CONCURRENCY || '3', 10); -const TEMPERATURE = parseFloat(process.env.LLM_TEMPERATURE || '0.2'); + +/** + * Reads a numeric env var, falling back to the default when it is missing, + * not a number or below the minimum (e.g. LLM_BATCH_SIZE=0 would loop forever). + */ +function numberFromEnv(name, defaultValue, { min, integer = true }) { + const raw = process.env[name]; + if (raw === undefined || raw === '') return defaultValue; + const value = integer ? Number.parseInt(raw, 10) : Number.parseFloat(raw); + if (!Number.isFinite(value) || value < min) { + console.warn(`Invalid ${name}="${raw}", using default ${defaultValue}`); + return defaultValue; + } + return value; +} + +const BATCH_SIZE = numberFromEnv('LLM_BATCH_SIZE', 25, { min: 1 }); +const CONTEXT_SIZE = numberFromEnv('LLM_CONTEXT_SIZE', 5, { min: 0 }); +const CONCURRENCY = numberFromEnv('LLM_CONCURRENCY', 3, { min: 1 }); +const TEMPERATURE = numberFromEnv('LLM_TEMPERATURE', 0.2, { min: 0, integer: false }); const JSON_MODE = process.env.LLM_JSON_MODE !== 'false'; const REQUEST_TIMEOUT = 180000; // 3 minutes per request const FALLBACK_COOLDOWN_MS = 5 * 60 * 1000; // skip a failing model for 5 minutes -const MAX_HTTP_RETRIES = parseInt(process.env.LLM_MAX_RETRIES || '5', 10); +const MAX_HTTP_RETRIES = numberFromEnv('LLM_MAX_RETRIES', 5, { min: 1 }); // Models that recently failed over, mapped to the time they can be used again const cooldownUntil = new Map(); @@ -195,7 +211,10 @@ async function translateBatch(systemPrompt, entries, context, title) { } return entries.map(({ i }) => byId.get(i)); } catch (error) { - if (error.status) throw error; // HTTP errors were already retried + // Contract: errors with a .status come from requestCompletion (HTTP errors, + // or 503 for network failures) and were already retried there. Splitting + // the batch would not help, so they bypass the retry/split path. + if (error.status) throw error; lastError = error; console.warn(`Invalid LLM batch response (attempt ${attempt}): ${error.message}`); } From 1e873cdc8f6cbacc658cb8761040f9eeb27cb992 Mon Sep 17 00:00:00 2001 From: Giovanny Aranda Date: Sun, 25 Oct 2026 13:09:51 +0100 Subject: [PATCH 6/6] fix: address second PR review - Treat an empty or missing model response as a malformed response (retry, then split the batch) instead of a network failure that was retried with backoff and reported as "LLM API unreachable". - Cap Retry-After waits at 60 seconds. - Only put a model on cooldown for 429, 5xx and network errors; other HTTP errors fall back for that request only. - Discard saved resume progress when the source texts change, using a hash instead of comparing only the number of blocks. - Stop returning originalError from extract_subtitles and mask media directory paths in its error message. --- server/routes/subtitle.js | 11 +++++---- server/services/llm.js | 45 ++++++++++++++++++++++------------- server/services/translator.js | 21 +++++++++++++--- 3 files changed, 53 insertions(+), 24 deletions(-) diff --git a/server/routes/subtitle.js b/server/routes/subtitle.js index 48a86d1..b950c8a 100644 --- a/server/routes/subtitle.js +++ b/server/routes/subtitle.js @@ -122,10 +122,14 @@ router.post('/extract_subtitles', async (req, res) => { await extractSubtitles(videoPath, outputPath); res.json({ path: outputPath }); } catch (error) { + // Full error stays in the server log; ffmpeg messages contain absolute paths console.error('Error extracting subtitles:', error); // Format a user-friendly error message with technical details - let userMessage = 'Failed to extract subtitles: ' + (error.message || 'Unknown error'); + const safeMessage = (error.message || 'Unknown error') + .replaceAll(resolve(DATA_DIR), '') + .replaceAll(resolve(MOVIES_DIR), ''); + let userMessage = 'Failed to extract subtitles: ' + safeMessage; let statusCode = 500; // Handle specific ffmpeg errors @@ -137,10 +141,7 @@ router.post('/extract_subtitles', async (req, res) => { statusCode = 422; } - res.status(statusCode).json({ - message: userMessage, - originalError: error.toString() - }); + res.status(statusCode).json({ message: userMessage }); } }); diff --git a/server/services/llm.js b/server/services/llm.js index 7b55b72..28ff5fc 100644 --- a/server/services/llm.js +++ b/server/services/llm.js @@ -31,6 +31,7 @@ const TEMPERATURE = numberFromEnv('LLM_TEMPERATURE', 0.2, { min: 0, integer: fal const JSON_MODE = process.env.LLM_JSON_MODE !== 'false'; const REQUEST_TIMEOUT = 180000; // 3 minutes per request const FALLBACK_COOLDOWN_MS = 5 * 60 * 1000; // skip a failing model for 5 minutes +const MAX_RETRY_AFTER_S = 60; // never sleep longer than this on a Retry-After header const MAX_HTTP_RETRIES = numberFromEnv('LLM_MAX_RETRIES', 5, { min: 1 }); // Models that recently failed over, mapped to the time they can be used again @@ -106,21 +107,15 @@ async function requestCompletion(model, systemPrompt, userContent, maxRetries) { } for (let attempt = 1; ; attempt++) { + let response; try { - const response = await axios.post(`${BASE_URL}/chat/completions`, body, { + response = await axios.post(`${BASE_URL}/chat/completions`, body, { headers: { 'Content-Type': 'application/json', ...(process.env.LLM_API_KEY && { Authorization: `Bearer ${process.env.LLM_API_KEY}` }), }, timeout: REQUEST_TIMEOUT, }); - usage.prompt_tokens += response.data.usage?.prompt_tokens || 0; - usage.completion_tokens += response.data.usage?.completion_tokens || 0; - const content = response.data.choices?.[0]?.message?.content; - if (typeof content !== 'string') { - throw new Error('LLM response has no message content'); - } - return content; } catch (error) { const status = error.response?.status; const retryable = !status || status === 429 || status >= 500; @@ -137,19 +132,32 @@ async function requestCompletion(model, systemPrompt, userContent, maxRetries) { enhanced.status = 503; throw enhanced; } - // Honor Retry-After when present, otherwise exponential backoff capped at 30s + // Honor Retry-After when present (capped), otherwise exponential backoff capped at 30s const retryAfter = parseInt(error.response?.headers?.['retry-after'], 10); - const delay = retryAfter > 0 ? retryAfter * 1000 : Math.min(2000 * 2 ** (attempt - 1), 30000); + const delay = retryAfter > 0 + ? Math.min(retryAfter, MAX_RETRY_AFTER_S) * 1000 + : Math.min(2000 * 2 ** (attempt - 1), 30000); console.warn(`LLM request to ${model} failed (${status || error.code}), retrying in ${delay / 1000}s...`); await new Promise((resolve) => setTimeout(resolve, delay)); + continue; } + + usage.prompt_tokens += response.data.usage?.prompt_tokens || 0; + usage.completion_tokens += response.data.usage?.completion_tokens || 0; + const content = response.data.choices?.[0]?.message?.content; + if (typeof content !== 'string' || content.trim() === '') { + // No .status: handled as a malformed response (retry, then split the batch) + throw new Error(`LLM response from ${model} has no message content`); + } + return content; } } /** * Sends a chat request, falling back to LLM_FALLBACK_MODELS in order when a - * model keeps failing. Models with a fallback after them fail over quickly, - * and a model that failed over is skipped for a while. + * model keeps failing. Models with a fallback after them fail over quickly. + * Only signs of an unhealthy model (429, 5xx, network) put it on cooldown; + * other HTTP errors (e.g. a 400 for one request) fall back for that request only. */ async function chatCompletion(systemPrompt, userContent) { const models = getModels(); @@ -161,10 +169,15 @@ async function chatCompletion(systemPrompt, userContent) { cooldownUntil.delete(models[i]); return content; } catch (error) { - // Auth errors would fail the same way on every model - if (isLast || error.status === 401 || error.status === 403) throw error; - cooldownUntil.set(models[i], Date.now() + FALLBACK_COOLDOWN_MS); - console.warn(`${error.message}; falling back to ${models[i + 1]} for the next 5 minutes`); + // Malformed responses (no .status) are handled by translateBatch, and + // auth errors would fail the same way on every model + if (isLast || !error.status || error.status === 401 || error.status === 403) throw error; + const unhealthy = error.status === 429 || error.status >= 500; + if (unhealthy) { + cooldownUntil.set(models[i], Date.now() + FALLBACK_COOLDOWN_MS); + } + console.warn(`${error.message}; falling back to ${models[i + 1]}` + + (unhealthy ? ' for the next 5 minutes' : ' for this request')); } } } diff --git a/server/services/translator.js b/server/services/translator.js index 5718a3d..1c06e2a 100644 --- a/server/services/translator.js +++ b/server/services/translator.js @@ -1,8 +1,16 @@ import fs from 'fs'; +import { createHash } from 'crypto'; import { parseSRT, stringifySRT } from '../utils/srt.js'; import { buildTextBatches, getTranslatedFilePath, getUsageStats, translateTexts } from './deepl.js'; import { getLLMConfigError, getLLMUsage, translateTextsLLM } from './llm.js'; +// Hash of the source texts each saved `partial` array was built from +const partialSources = new WeakMap(); + +function hashTexts(texts) { + return createHash('sha256').update(JSON.stringify(texts)).digest('hex'); +} + export function getProvider() { return (process.env.TRANSLATION_PROVIDER || 'deepl').toLowerCase() === 'llm' ? 'llm' : 'deepl'; } @@ -91,9 +99,16 @@ export async function translateSRT(filePath, sourceLang, targetLang, options = { const texts = toTranslate.map(item => item.text); // Discard saved progress if the file changed since the failed run - if (options.partial && options.partial.length !== texts.length) { - options.partial.length = 0; - options.partial.length = texts.length; + if (options.partial) { + const sourceHash = hashTexts(texts); + if (partialSources.get(options.partial) !== sourceHash) { + if (options.partial.some(text => text !== undefined)) { + console.log('Subtitle file changed since the last attempt, starting over'); + } + options.partial.length = 0; + options.partial.length = texts.length; + partialSources.set(options.partial, sourceHash); + } } const translatedTexts = provider === 'llm'