From 6deded85cf2e732c7e3963b707b04854bde90a6f Mon Sep 17 00:00:00 2001
From: Simon Alman
Date: Fri, 31 Jul 2026 13:23:52 +0100
Subject: [PATCH] feat(search): 3-pass subtitle search and configurable
preferred language with score penalties
---
src/app/admin/settings/lib/helpers.ts | 2 +
src/app/admin/settings/lib/types.ts | 2 +
.../settings/tabs/IndexersTab/IndexersTab.tsx | 65 ++++++++++++++++++-
.../admin/settings/indexer-options/route.ts | 61 +++++++++++------
src/lib/integrations/prowlarr.service.ts | 8 +++
.../processors/search-indexers.processor.ts | 4 ++
src/lib/services/config.service.ts | 23 +++++++
src/lib/utils/ranking-algorithm.ts | 28 ++++++++
.../configurable-language-filtering.test.ts | 41 ++++++++++++
tests/utils/language-filtering.test.ts | 51 +++++++++++++++
10 files changed, 264 insertions(+), 21 deletions(-)
create mode 100644 tests/utils/configurable-language-filtering.test.ts
create mode 100644 tests/utils/language-filtering.test.ts
diff --git a/src/app/admin/settings/lib/helpers.ts b/src/app/admin/settings/lib/helpers.ts
index e210b3133..8accb3a88 100644
--- a/src/app/admin/settings/lib/helpers.ts
+++ b/src/app/admin/settings/lib/helpers.ts
@@ -120,6 +120,8 @@ export const saveTabSettings = async (
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
skipUnreleased: settings.indexerOptions.skipUnreleased,
+ preferredLanguage: settings.indexerOptions.preferredLanguage,
+ languagePenaltyScore: settings.indexerOptions.languagePenaltyScore,
}),
}).then(res => {
if (!res.ok) throw new Error('Failed to save indexer options');
diff --git a/src/app/admin/settings/lib/types.ts b/src/app/admin/settings/lib/types.ts
index 46b4ab46f..badce4e81 100644
--- a/src/app/admin/settings/lib/types.ts
+++ b/src/app/admin/settings/lib/types.ts
@@ -88,6 +88,8 @@ export interface IndexerOptionsSettings {
* Backing config key: `indexer.skip_unreleased`.
*/
skipUnreleased: boolean;
+ preferredLanguage?: 'en' | 'de' | 'es' | 'fr' | 'all';
+ languagePenaltyScore?: number;
}
/**
diff --git a/src/app/admin/settings/tabs/IndexersTab/IndexersTab.tsx b/src/app/admin/settings/tabs/IndexersTab/IndexersTab.tsx
index c56bdce64..8536c1d51 100644
--- a/src/app/admin/settings/tabs/IndexersTab/IndexersTab.tsx
+++ b/src/app/admin/settings/tabs/IndexersTab/IndexersTab.tsx
@@ -146,7 +146,7 @@ export function IndexersTab({
-
+
+
+
+
+
+
+
+ Target audiobook language. Selecting "All" disables language filtering and score penalties.
+
+
+
+
+
+
+ onChange({
+ ...settings,
+ indexerOptions: {
+ ...settings.indexerOptions,
+ languagePenaltyScore: parseInt(e.target.value || '0', 10),
+ },
+ })
+ }
+ className="w-full rounded-md border-gray-300 dark:border-gray-600 bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100 shadow-sm focus:border-blue-500 focus:ring-blue-500 text-sm p-2"
+ />
+
+ Score penalty subtracted for non-matching language or language-learning course releases (default: 100).
+
+
+
diff --git a/src/app/api/admin/settings/indexer-options/route.ts b/src/app/api/admin/settings/indexer-options/route.ts
index bf70bb3ad..7f247264a 100644
--- a/src/app/api/admin/settings/indexer-options/route.ts
+++ b/src/app/api/admin/settings/indexer-options/route.ts
@@ -39,8 +39,14 @@ export async function GET(request: NextRequest) {
// Default ON: missing or any value other than 'false' is treated as enabled.
const skipUnreleased = value !== 'false';
+ const preferredLanguage = await configService.getPreferredLanguage();
+ const languagePenaltyScore = await configService.getLanguagePenaltyScore();
- return NextResponse.json({ skipUnreleased });
+ return NextResponse.json({
+ skipUnreleased,
+ preferredLanguage,
+ languagePenaltyScore,
+ });
} catch (error) {
logger.error('Failed to fetch indexer options', {
error: error instanceof Error ? error.message : String(error),
@@ -56,39 +62,54 @@ export async function GET(request: NextRequest) {
/**
* PUT /api/admin/settings/indexer-options
- * Persists indexer-wide options. Body: { skipUnreleased: boolean }
+ * Persists indexer-wide options. Body: { skipUnreleased?: boolean, preferredLanguage?: string, languagePenaltyScore?: number }
*/
export async function PUT(request: NextRequest) {
return requireAuth(request, async (req: AuthenticatedRequest) => {
return requireAdmin(req, async () => {
try {
const body = await request.json();
- const { skipUnreleased } = body ?? {};
-
- if (typeof skipUnreleased !== 'boolean') {
- return NextResponse.json(
- { error: 'skipUnreleased must be a boolean' },
- { status: 400 }
- );
- }
-
+ const { skipUnreleased, preferredLanguage, languagePenaltyScore } = body ?? {};
const configService = getConfigService();
- await configService.setMany([
- {
+ const updates: any[] = [];
+
+ if (typeof skipUnreleased === 'boolean') {
+ updates.push({
key: CONFIG_KEY,
value: String(skipUnreleased),
category: 'indexer',
description:
'Skip auto-searches for books with future release dates',
- },
- ]);
+ });
+ }
+
+ if (preferredLanguage && ['en', 'de', 'es', 'fr', 'all'].includes(String(preferredLanguage).toLowerCase())) {
+ updates.push({
+ key: 'search.preferred_language',
+ value: String(preferredLanguage).toLowerCase(),
+ category: 'search',
+ description: 'Preferred search language (en, de, es, fr, all)',
+ });
+ }
- // Explicitly clear cache for the key after write. `setMany` already
- // does this, but we make it visible here to guarantee fresh reads
- // by any sibling service that has cached the value.
- configService.clearCache(CONFIG_KEY);
+ if (languagePenaltyScore !== undefined) {
+ const score = parseInt(String(languagePenaltyScore), 10);
+ if (!isNaN(score) && score >= 0) {
+ updates.push({
+ key: 'search.language_penalty_score',
+ value: String(score),
+ category: 'search',
+ description: 'Language penalty score for non-matching search results',
+ });
+ }
+ }
+
+ if (updates.length > 0) {
+ await configService.setMany(updates);
+ configService.clearCache();
+ }
- logger.info('Indexer options updated', { skipUnreleased });
+ logger.info('Indexer options updated', { skipUnreleased, preferredLanguage, languagePenaltyScore });
return NextResponse.json({
success: true,
diff --git a/src/lib/integrations/prowlarr.service.ts b/src/lib/integrations/prowlarr.service.ts
index 2e32865a5..6ea69ddf3 100644
--- a/src/lib/integrations/prowlarr.service.ts
+++ b/src/lib/integrations/prowlarr.service.ts
@@ -225,6 +225,14 @@ export class ProwlarrService {
title,
];
+ // Pass 3: Subtitle-cleaned query (extract core title before colon or em-dash)
+ if (title.includes(':') || title.includes(' - ')) {
+ const cleanCoreTitle = title.split(/:|\s+-\s+/)[0].trim();
+ if (cleanCoreTitle && cleanCoreTitle.length > 3 && !queries.includes(cleanCoreTitle)) {
+ queries.push(cleanCoreTitle);
+ }
+ }
+
logger.info(`Searching with ${queries.length} query variations`, { queries });
const allResults: TorrentResult[] = [];
diff --git a/src/lib/processors/search-indexers.processor.ts b/src/lib/processors/search-indexers.processor.ts
index 11917cf4f..b5e287997 100644
--- a/src/lib/processors/search-indexers.processor.ts
+++ b/src/lib/processors/search-indexers.processor.ts
@@ -175,6 +175,8 @@ export async function processSearchIndexers(payload: SearchIndexersPayload): Pro
const ranker = getRankingAlgorithm();
const region = await configService.getAudibleRegion() as AudibleRegion;
const langConfig = getLanguageForRegion(region);
+ const preferredLanguage = await configService.getPreferredLanguage();
+ const languagePenaltyScore = await configService.getLanguagePenaltyScore();
// Rank results with indexer priorities and flag configs
// Note: rankTorrents now filters out results < 20 MB internally
@@ -190,6 +192,8 @@ export async function processSearchIndexers(payload: SearchIndexersPayload): Pro
requireAuthor: true, // Automatic mode - prevent wrong authors
stopWords: langConfig.stopWords,
characterReplacements: langConfig.characterReplacements,
+ preferredLanguage,
+ languagePenaltyScore,
});
// Log filter results
diff --git a/src/lib/services/config.service.ts b/src/lib/services/config.service.ts
index ae597cb5c..c760f4f14 100644
--- a/src/lib/services/config.service.ts
+++ b/src/lib/services/config.service.ts
@@ -237,6 +237,29 @@ export class ConfigurationService {
return (region as AudibleRegion) || DEFAULT_AUDIBLE_REGION;
}
+ /**
+ * Get preferred audiobook search language ('en' | 'de' | 'es' | 'fr' | 'all')
+ */
+ async getPreferredLanguage(): Promise<'en' | 'de' | 'es' | 'fr' | 'all'> {
+ const dbValue = await this.get('search.preferred_language');
+ const envValue = process.env.PREFERRED_AUDIOBOOK_LANGUAGE;
+ const value = (dbValue || envValue || 'en').toLowerCase().trim();
+ if (['en', 'de', 'es', 'fr', 'all'].includes(value)) {
+ return value as 'en' | 'de' | 'es' | 'fr' | 'all';
+ }
+ return 'en';
+ }
+
+ /**
+ * Get language penalty score for non-matching search results
+ */
+ async getLanguagePenaltyScore(): Promise {
+ const dbValue = await this.get('search.language_penalty_score');
+ const envValue = process.env.LANGUAGE_PENALTY_SCORE;
+ const val = parseInt(dbValue || envValue || '100', 10);
+ return isNaN(val) ? 100 : val;
+ }
+
/**
* Clear the cache for a specific key or all keys
*/
diff --git a/src/lib/utils/ranking-algorithm.ts b/src/lib/utils/ranking-algorithm.ts
index 5b39c8d53..44377ca90 100644
--- a/src/lib/utils/ranking-algorithm.ts
+++ b/src/lib/utils/ranking-algorithm.ts
@@ -42,6 +42,8 @@ export interface RankTorrentsOptions {
requireAuthor?: boolean; // Enforce author presence check (default: true)
stopWords?: string[]; // Language-specific stop words for matching
characterReplacements?: Record; // Language-specific char replacements (e.g. ß→ss)
+ preferredLanguage?: 'en' | 'de' | 'es' | 'fr' | 'all'; // Target language or 'all' to disable filter
+ languagePenaltyScore?: number; // Score penalty for non-matching language (default: 100)
}
export interface EbookTorrentRequest {
@@ -175,6 +177,32 @@ export class RankingAlgorithm {
});
}
+ // Configurable Preferred Language & Penalty Scoring
+ const preferredLang = options?.preferredLanguage ?? 'en';
+ const penaltyScore = options?.languagePenaltyScore ?? 100;
+
+ if (preferredLang !== 'all') {
+ const isRequestCourse = /learn|language|course|pimsleur|berlitz/i.test(audiobook.title);
+ const NON_ENGLISH_PATTERN = /\[?(german|deutsch|hörbuch|french|français|livre audio|spanish|español|audiolibro|italian|italiano|dutch|polish|russian)\]?/i;
+ const COURSE_PATTERN = /pimsleur|learn\s+(spanish|german|french|italian|japanese|chinese|russian)|berlitz|language\s+course/i;
+
+ if (NON_ENGLISH_PATTERN.test(torrent.title)) {
+ bonusModifiers.push({
+ type: 'custom',
+ value: -1.0,
+ points: -Math.abs(penaltyScore),
+ reason: `Non-English language tag detected in release title (-${penaltyScore} penalty)`,
+ });
+ } else if (!isRequestCourse && COURSE_PATTERN.test(torrent.title)) {
+ bonusModifiers.push({
+ type: 'custom',
+ value: -1.0,
+ points: -Math.abs(penaltyScore),
+ reason: `Language learning course tag detected in release title (-${penaltyScore} penalty)`,
+ });
+ }
+ }
+
// Sum all bonus points
const bonusPoints = bonusModifiers.reduce((sum, mod) => sum + mod.points, 0);
diff --git a/tests/utils/configurable-language-filtering.test.ts b/tests/utils/configurable-language-filtering.test.ts
new file mode 100644
index 000000000..49c87b4e7
--- /dev/null
+++ b/tests/utils/configurable-language-filtering.test.ts
@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest';
+import { rankTorrents, TorrentResult, AudiobookRequest } from '@/lib/utils/ranking-algorithm';
+
+describe('Configurable Preferred Language and Penalty Scoring', () => {
+ const audiobook: AudiobookRequest = {
+ title: 'The Expanse 03: Abaddon\'s Gate',
+ author: 'James S. A. Corey',
+ };
+
+ const germanTorrent: TorrentResult = {
+ title: 'James S. A. Corey - Abaddon\'s Gate [German] Hörbuch',
+ size: 500000000,
+ publishDate: new Date(),
+ downloadUrl: 'http://example.com/de.nzb',
+ guid: 'guid-de',
+ indexer: 'Nzbhydra2',
+ };
+
+ it('should bypass language penalties when preferredLanguage is set to "all"', () => {
+ const ranked = rankTorrents([germanTorrent], audiobook, {
+ preferredLanguage: 'all',
+ });
+
+ const germanRanked = ranked.find(r => r.guid === 'guid-de');
+ expect(germanRanked?.finalScore).toBeGreaterThan(0);
+ expect(germanRanked?.bonusModifiers.some(m => m.points < 0)).toBe(false);
+ });
+
+ it('should apply custom languagePenaltyScore when specified', () => {
+ const ranked = rankTorrents([germanTorrent], audiobook, {
+ preferredLanguage: 'en',
+ languagePenaltyScore: 250,
+ });
+
+ const germanRanked = ranked.find(r => r.guid === 'guid-de');
+ const penaltyMod = germanRanked?.bonusModifiers.find(m => m.points < 0);
+
+ expect(penaltyMod?.points).toBe(-250);
+ expect(penaltyMod?.reason).toContain('-250 penalty');
+ });
+});
diff --git a/tests/utils/language-filtering.test.ts b/tests/utils/language-filtering.test.ts
new file mode 100644
index 000000000..88f9b1704
--- /dev/null
+++ b/tests/utils/language-filtering.test.ts
@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { rankTorrents, TorrentResult, AudiobookRequest } from '@/lib/utils/ranking-algorithm';
+
+describe('English Language Filtering and Subtitle Search', () => {
+ const audiobook: AudiobookRequest = {
+ title: 'The Expanse 03: Abaddon\'s Gate',
+ author: 'James S. A. Corey',
+ };
+
+ it('should penalize non-English releases with a -100 penalty', () => {
+ const englishTorrent: TorrentResult = {
+ title: 'James S. A. Corey - The Expanse 03 - Abaddon\'s Gate (Unabr - 64k [2013])',
+ size: 500000000,
+ publishDate: new Date(),
+ downloadUrl: 'http://example.com/en.nzb',
+ guid: 'guid-1',
+ indexer: 'Nzbhydra2',
+ };
+
+ const germanTorrent: TorrentResult = {
+ title: 'James S. A. Corey - Abaddon\'s Gate [German] Hörbuch',
+ size: 500000000,
+ publishDate: new Date(),
+ downloadUrl: 'http://example.com/de.nzb',
+ guid: 'guid-2',
+ indexer: 'Nzbhydra2',
+ };
+
+ const ranked = rankTorrents([englishTorrent, germanTorrent], audiobook, {
+ requireAuthor: true,
+ });
+
+ const germanRanked = ranked.find(r => r.guid === 'guid-2');
+ expect(germanRanked?.finalScore).toBeLessThan(0);
+ expect(ranked[0].guid).toBe('guid-1');
+ });
+
+ it('should penalize language learning courses for standard book requests', () => {
+ const courseTorrent: TorrentResult = {
+ title: 'Pimsleur German Level 1 - Learn German Audio Course',
+ size: 500000000,
+ publishDate: new Date(),
+ downloadUrl: 'http://example.com/course.nzb',
+ guid: 'guid-3',
+ indexer: 'Nzbhydra2',
+ };
+
+ const ranked = rankTorrents([courseTorrent], audiobook);
+ expect(ranked[0].finalScore).toBeLessThan(0);
+ });
+});