release: Bazarr+ v2.6.2 (Clockwork)

.github/workflows/ci.yml

@@ -181,6 +181,7 @@ jobs:
             tests/bazarr/test_rar_extraction_production_config.py \
             tests/bazarr/test_provider_hub_auto_install_optin.py \
             tests/bazarr/test_provider_hub_archive_select.py \
+            tests/bazarr/test_provider_hub_archive_candidates.py \
             tests/bazarr/test_archive_member_matching.py \
             tests/bazarr/test_provider_hub_worker_timeout.py \
             tests/bazarr/test_arr_instances_schema.py \
@@ -203,6 +204,7 @@ jobs:
             tests/bazarr/test_processing_sync_substep.py \
             tests/bazarr/test_mass_download_path_mapping.py \
             tests/bazarr/test_processing_postprocessing.py \
+            tests/bazarr/test_upload_background_sync.py \
             tests/bazarr/test_sync_progress_report.py \
             tests/bazarr/test_subsync_engines.py \
             tests/bazarr/test_autosubsync_diagnostics.py \
@@ -276,6 +278,11 @@ jobs:
             tests/bazarr/test_jellyfin_client.py \
             tests/bazarr/test_jellyfin_operations.py \
             tests/bazarr/test_logging_filters.py \
+            tests/bazarr/test_openrouter_provider_routing.py \
+            tests/bazarr/test_openrouter_model_migration.py \
+            tests/bazarr/test_openrouter_translator_partial.py \
+            tests/bazarr/test_openrouter_translator.py \
+            tests/bazarr/test_translator_model_migration.py \
             tests/bazarr/test_provider_hub_install_serialization.py \
             tests/bazarr/test_provider_hub_language_fallback.py \
             tests/bazarr/test_provider_hub_release_scoring.py \
@@ -289,12 +296,14 @@ jobs:
             tests/bazarr/test_sonarr_sync_episodes.py \
             tests/bazarr/test_sql_profiler.py \
             tests/bazarr/test_subtitle_content_sync_outputs.py \
+            tests/bazarr/test_subtitle_destination_path.py \
             tests/bazarr/test_subtitle_download_api.py \
             tests/bazarr/test_subtitles_pool.py \
             tests/bazarr/test_swagger_static.py \
             tests/bazarr/test_supervisor_proxy.py \
             tests/bazarr/test_supervisor_stages.py \
             tests/bazarr/test_tracemalloc_dumper.py \
+            tests/bazarr/test_translate_job_media_name.py \
             tests/bazarr/test_translator_auth.py \
             tests/bazarr/test_upgrade_embedded_history.py \
             tests/subliminal_patch/test_animetosho.py \
@@ -328,6 +337,7 @@ jobs:
             tests/bazarr/test_arr_pg_cutover_migration.py \
             tests/bazarr/test_editor_instance_scope.py \
             tests/bazarr/test_history_blacklist_scope.py \
+            tests/bazarr/test_history_owner_resolution.py \
             tests/bazarr/test_local_id_actions.py \
             tests/bazarr/test_navigation_local_ids.py \
             tests/bazarr/test_provider_blacklist_instance_scope.py \
@@ -350,6 +360,7 @@ jobs:
             tests/bazarr/test_indexer_owner_scope.py \
             tests/bazarr/test_indexer_path_mapping_owner.py \
             tests/bazarr/test_provider_hub_worker_reaper.py \
+            tests/bazarr/test_provider_hub_worker_errors.py \
             tests/bazarr/test_job_module_identity.py \
             tests/bazarr/test_sonarr_sync_memory.py \
             tests/bazarr/test_anilist_index.py \

README.md

@@ -246,7 +246,7 @@ Bazarr+ solves it with a **Provider Priority toggle** in Settings > Providers. W
 Upstream has Google Translate, Gemini, and Lingarr. Bazarr+ adds **OpenRouter** as a fourth translator engine, giving access to 300+ LLMs (Claude, Gemini, GPT, LLaMA, Grok, and more) plus any custom model ID from openrouter.ai. It runs as a separate microservice with an async job queue supporting 1-5 concurrent jobs and 1-8 parallel batches. Features include:
 - **Translate from the subtitle action menu**: click (...) on a missing subtitle row, pick an existing source subtitle to translate from
 - **Batch translation** for entire series/movie libraries from the Wanted pages
-- **Dedicated settings page** with 4 zones: engine picker, connection config, model tuning (temperature, reasoning mode, parallel batches), and a live status panel showing queue stats, job progress, token usage, cost, and speed
+- **Dedicated settings page** with 4 zones: engine picker, connection config, model tuning (temperature, reasoning mode, provider routing, parallel batches), and a live status panel showing queue stats, job progress, token usage, cost, and speed
 - **Model details** fetched live from the OpenRouter API with per-million token pricing, per-episode/movie cost estimates, context length, and prompt caching indicators
 - **AES-256-GCM encryption** for API keys in transit between Bazarr and the translator service, with a Test Connection button that validates encryption and API key status before saving
 - **Auto disk scan** triggers Sonarr/Radarr to rescan after translation completes
@@ -455,7 +455,7 @@ The OpenSubtitles.org plugin no longer uses environment variables. Configure its
 1. Go to **Settings** > **AI Translator**
 2. Select **"AI Subtitle Translator"** as the translator engine
 3. Enter your **OpenRouter API Key** (get one at [openrouter.ai/keys](https://openrouter.ai/keys))
-4. Choose your preferred **AI Model** (Google: Gemini 2.5 Flash Lite Preview 09-2025 recommended)
+4. Choose your preferred **AI Model** (`google/gemini-2.5-flash-lite` recommended)
 5. Save and test with a manual translation
 
 </details>

bazarr/api/subtitles/content.py

@@ -21,6 +21,7 @@
 from subtitles.indexer.movies import store_subtitles_movie
 from subtitles.indexer.series import store_subtitles
 from subtitles.processing import ProcessSubtitlesResult
+from subtitles.tools.subsync_engines import subtitle_mutation, subtitle_write_locks
 from utilities.helper import get_target_folder
 from utilities.path_mappings import path_mappings
 
@@ -813,13 +814,6 @@ def _save_subtitle_content(media_type, media_id, language_code, arr_instance_id=
 
     subtitle_path, metadata = result
 
-    # Optimistic locking via ETag (optional but recommended)
-    if_match = request.headers.get('If-Match')
-    if if_match:
-        current_etag = generate_etag(subtitle_path)
-        if if_match.strip('"') != current_etag:
-            return 'Subtitle file has been modified since last read', 412
-
     data = request.get_json()
     if not data or 'content' not in data:
         return 'Request body must include "content" field', 400
@@ -838,8 +832,19 @@ def _save_subtitle_content(media_type, media_id, language_code, arr_instance_id=
     if len(encoded) > MAX_FILE_SIZE:
         return f'Content too large ({len(encoded)} bytes, max {MAX_FILE_SIZE})', 413
 
+    video_path = path_mappings.path_replace_instance(
+        metadata['mediaPath'], metadata.get('arrInstanceId', arr_instance_id), media_type)
     try:
-        _write_bytes_atomically(subtitle_path, encoded)
+        with subtitle_write_locks(video_path, subtitle_path):
+            if not os.path.isfile(subtitle_path):
+                return 'Subtitle file or directory not found', 404
+            if_match = request.headers.get('If-Match')
+            if if_match and if_match.strip('"') != generate_etag(subtitle_path):
+                return 'Subtitle file has been modified since last read', 412
+            with subtitle_mutation(video_path, subtitle_path):
+                _write_bytes_atomically(subtitle_path, encoded)
+                _apply_subtitle_chmod(subtitle_path)
+            new_etag = generate_etag(subtitle_path)
     except FileNotFoundError:
         return 'Subtitle file or directory not found', 404
     except PermissionError:
@@ -849,11 +854,7 @@ def _save_subtitle_content(media_type, media_id, language_code, arr_instance_id=
             return 'No space left on device', 507
         raise
 
-    _apply_subtitle_chmod(subtitle_path)
-
     _refresh_media_subtitles(media_type, media_id, metadata)
-
-    new_etag = generate_etag(subtitle_path)
     response = make_response('', 204)
     response.headers['ETag'] = f'"{new_etag}"'
     return response
@@ -900,15 +901,20 @@ def promote_sync_subtitle(media_type, media_id, target_language, source_language
     if os.path.realpath(source_path) == os.path.realpath(target_path):
         return 'Source and target subtitles are the same file', 400
 
+    video_path = path_mappings.path_replace_instance(
+        metadata['mediaPath'], metadata.get('arrInstanceId', arr_instance_id), media_type)
     try:
-        file_size = os.path.getsize(source_path)
-        if file_size > MAX_FILE_SIZE:
-            return f'Subtitle file too large ({file_size} bytes, max {MAX_FILE_SIZE})', 413
-
-        with open(source_path, 'rb') as source_file:
-            data = source_file.read()
-
-        _write_bytes_atomically(target_path, data)
+        with subtitle_write_locks(video_path, source_path, target_path):
+            file_size = os.path.getsize(source_path)
+            if file_size > MAX_FILE_SIZE:
+                return f'Subtitle file too large ({file_size} bytes, max {MAX_FILE_SIZE})', 413
+            if not os.path.isfile(target_path):
+                return 'Subtitle file or directory not found', 404
+            with open(source_path, 'rb') as source_file:
+                data = source_file.read()
+            with subtitle_mutation(video_path, target_path):
+                _write_bytes_atomically(target_path, data)
+                _apply_subtitle_chmod(target_path)
     except FileNotFoundError:
         return 'Subtitle file or directory not found', 404
     except PermissionError:
@@ -918,16 +924,17 @@ def promote_sync_subtitle(media_type, media_id, target_language, source_language
             return 'No space left on device', 507
         raise
 
-    _apply_subtitle_chmod(target_path)
-    _log_promoted_sync_history(
-        media_type=media_type,
-        media_id=media_id,
-        target_language=target_language,
-        source_language=source_language,
-        target_path=target_path,
-        metadata=metadata,
-    )
-    _refresh_media_subtitles(media_type, media_id, metadata)
+    try:
+        _refresh_media_subtitles(media_type, media_id, metadata)
+    finally:
+        _log_promoted_sync_history(
+            media_type=media_type,
+            media_id=media_id,
+            target_language=target_language,
+            source_language=source_language,
+            target_path=target_path,
+            metadata=metadata,
+        )
 
     return {
         'sourceLanguage': source_language,
@@ -1096,24 +1103,20 @@ def _create_subtitle(media_type, media_id, arr_instance_id=None):
             subtitle_path.startswith(target_folder_real + os.sep)):
         return 'Invalid subtitle path', 400
 
-    # Check for existing file
-    if os.path.isfile(subtitle_path):
-        return 'Subtitle file already exists', 409
-
     # Encode content
     encoded = content.encode('utf-8')
     if len(encoded) > MAX_FILE_SIZE:
         return f'Content too large ({len(encoded)} bytes, max {MAX_FILE_SIZE})', 413
 
-    # Write atomically
+    # Check and create under the same mutation lock as replacements.
     try:
-        fd, tmp_path = tempfile.mkstemp(dir=target_folder)
-        try:
-            os.write(fd, encoded)
-        finally:
-            os.close(fd)
+        with subtitle_write_locks(video_path, subtitle_path):
+            if os.path.isfile(subtitle_path):
+                return 'Subtitle file already exists', 409
+            with subtitle_mutation(video_path, subtitle_path):
+                _write_bytes_atomically(subtitle_path, encoded)
+                _apply_subtitle_chmod(subtitle_path)
 
-        os.replace(tmp_path, subtitle_path)
     except FileNotFoundError:
         return 'Target directory not found', 404
     except PermissionError:
@@ -1123,14 +1126,6 @@ def _create_subtitle(media_type, media_id, arr_instance_id=None):
             return 'No space left on device', 507
         raise
 
-    # Apply chmod if configured
-    if settings.general.chmod_enabled:
-        try:
-            chmod_value = int(settings.general.chmod, 8)
-            os.chmod(subtitle_path, chmod_value)
-        except Exception:
-            pass
-
     # Force re-scan subtitles from disk using the media (video) path
     if media_type == 'episode':
         store_subtitles(row.path, video_path, use_cache=False, arr_instance_id=arr_instance_id)

bazarr/api/translator/translator.py

@@ -8,6 +8,7 @@
 from app.config import settings
 from app.jobs_queue import jobs_queue
 from subtitles.tools.translate.services.auth import get_translator_auth_headers
+from subtitles.tools.translate.services.openrouter_translator import build_provider_config
 from ..utils import authenticate
 
 api_ns_translator = Namespace('Translator', description='AI Subtitle Translator service operations')
@@ -124,6 +125,7 @@ def post(self):
                 "apiKey": api_key,
                 "model": settings.translator.openrouter_model,
                 "temperature": settings.translator.openrouter_temperature,
+                "provider": build_provider_config(),
             }
         }
 

bazarr/app/config.py

@@ -238,12 +238,17 @@ def check_parser_binary(value):
     Validator('translator.lingarr_url', must_exist=True, default='http://lingarr:9876', is_type_of=str),
     Validator('translator.openrouter_url', must_exist=True, default='http://subtitle-translator:8765', is_type_of=str),
     Validator('translator.openrouter_api_key', must_exist=True, default='', is_type_of=str, cast=str),
-    Validator('translator.openrouter_model', must_exist=True, default='google/gemini-2.5-flash-preview-05-20', is_type_of=str),
+    Validator('translator.openrouter_model', must_exist=True, default='google/gemini-2.5-flash-lite', is_type_of=str),
     Validator('translator.openrouter_temperature', must_exist=True, default=0.3, is_type_of=float),
     Validator('translator.openrouter_max_concurrent', must_exist=True, default=2, is_type_of=int, gte=1, lte=10),
     Validator('translator.openrouter_reasoning', must_exist=True, default='disabled', is_type_of=str,
               is_in=['disabled', 'low', 'medium', 'high']),
     Validator('translator.openrouter_parallel_batches', must_exist=True, default=4, is_type_of=int, gte=1, lte=8),
+    # Which OpenRouter provider serves the model: throughput (the sidecar's historical default),
+    # nitro/floor (OpenRouter's slug shortcuts, which also unlock the priority/flex tiers),
+    # price, latency, or OpenRouter's own load balancing.
+    Validator('translator.openrouter_provider_routing', must_exist=True, default='throughput', is_type_of=str,
+              is_in=['throughput', 'nitro', 'price', 'floor', 'latency', 'default']),
     Validator('translator.openrouter_encryption_key', must_exist=True, default='', is_type_of=str, cast=str),
     Validator('translator.lingarr_token', must_exist=True, default='', is_type_of=str, cast=str),
 
@@ -727,6 +732,26 @@ def write_config():
                 _force_first_save_migration = False
 
 
+# OpenRouter retired these ids, including Bazarr's default and documented recommendation.
+# Users who never chose a model would otherwise get a model-not-found error.
+RETIRED_OPENROUTER_MODELS = {
+    'google/gemini-2.5-flash-preview-05-20': 'google/gemini-2.5-flash',
+    'google/gemini-2.5-flash-lite-preview-06-17': 'google/gemini-2.5-flash-lite',
+    'google/gemini-2.5-flash-lite-preview-09-2025': 'google/gemini-2.5-flash-lite',
+    'google/gemini-3-pro-preview': 'google/gemini-3.1-pro-preview',
+}
+
+
+def migrate_retired_openrouter_model(settings) -> bool:
+    current_model = settings.translator.openrouter_model.strip()
+    replacement = RETIRED_OPENROUTER_MODELS.get(current_model)
+    if replacement is None:
+        return False
+    settings.translator.openrouter_model = replacement
+    logging.warning(f'Replaced retired OpenRouter model {current_model} with {replacement}')  # noqa: G004
+    return True
+
+
 base_url = settings.general.base_url.rstrip('/')
 
 array_keys = ['excluded_tags',
@@ -790,6 +815,8 @@ def write_config():
         settings.translator.gemini_keys = [legacy_key]
     del settings.translator.gemini_key
 
+migrate_retired_openrouter_model(settings)
+
 # save updated settings to file
 write_config()