Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion documentation/phase3/ranking-algorithm.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ Evaluates and scores torrents to automatically select best audiobook download.
- ✅ **Context-aware filtering (3 tests)**
- ✅ **API compatibility (2 tests)**
- ✅ **CamelCase and punctuation separator handling (7 tests)**
- ✅ **Minimum size-per-runtime filter (3 tests)**

**Tested edge cases prevent regressions from previous tweaks:**
- "We Are Legion (We Are Bob)" matching with/without subtitle
Expand All @@ -32,6 +33,14 @@ Evaluates and scores torrents to automatically select best audiobook download.
- **All results shown in interactive mode regardless of author**
- **Middle initials, name order, and role filtering for author matching**

## Pre-Filters (Audiobooks)

- < 20 MB: always filtered (ebooks/samples)
- `minMBPerMinute` (opt-in): filtered when `sizeMB / durationMinutes` < value; skipped if runtime unknown
- Automatic search (`search-indexers.processor.ts`): `0.15` (~21 kbps; complete releases seen down to 0.21)
- Interactive search: unset (user decides)
- Catches single files from multi-file Usenet posts (e.g. 57 MB chapter for 1182 min book = 0.05 MB/min, scored 79.7 without filter)

## Scoring Criteria (100 points max)

**1. Title/Author Match (60 pts max) - MOST IMPORTANT**
Expand Down Expand Up @@ -229,6 +238,7 @@ interface RankTorrentsOptions {
indexerPriorities?: Map<number, number>; // indexerId -> priority (1-25)
flagConfigs?: IndexerFlagConfig[]; // Flag bonus configurations
requireAuthor?: boolean; // Enforce author check (default: true)
minMBPerMinute?: number; // Size/runtime floor (default: off)
}

interface BonusModifier {
Expand Down Expand Up @@ -282,7 +292,8 @@ function rankTorrents(
const ranked = rankTorrents(torrents, audiobook, {
indexerPriorities,
flagConfigs,
requireAuthor: true // Default - prevents wrong authors
requireAuthor: true, // Default - prevents wrong authors
minMBPerMinute: 0.15 // Rejects single chapters/partial posts
});

const topResult = ranked[0]; // Safe to auto-download
Expand Down
7 changes: 6 additions & 1 deletion src/lib/processors/search-indexers.processor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ import { getLanguageForRegion } from '../constants/language-config';
import { filterBlockedResults } from '../utils/filter-blocked-results';
import type { AudibleRegion } from '../types/audible';

// Auto-search size floor (~21 kbps). Complete releases go as low as ~0.21 MB/min;
// single chapters from multi-file Usenet posts are ~0.05.
const MIN_AUTO_MB_PER_MINUTE = 0.15;

const MAX_RANKED_RESULTS = 100;

/**
Expand Down Expand Up @@ -189,14 +193,15 @@ export async function processSearchIndexers(payload: SearchIndexersPayload): Pro
indexerPriorities,
flagConfigs,
requireAuthor: true, // Automatic mode - prevent wrong authors
minMBPerMinute: MIN_AUTO_MB_PER_MINUTE, // Automatic mode - reject single chapters/partial posts
stopWords: langConfig.stopWords,
characterReplacements: langConfig.characterReplacements,
});

// Log filter results
const postFilterCount = rankedResults.length;
if (postFilterCount < preFilterCount) {
logger.info(`Filtered out ${preFilterCount - postFilterCount} results < ${sizeMBThreshold} MB`);
logger.info(`Filtered out ${preFilterCount - postFilterCount} results < ${sizeMBThreshold} MB or < ${MIN_AUTO_MB_PER_MINUTE} MB/min of runtime`);
}

// Dual threshold filtering:
Expand Down
12 changes: 10 additions & 2 deletions src/lib/utils/ranking-algorithm.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ export interface RankTorrentsOptions {
requireAuthor?: boolean; // Enforce author presence check (default: true)
stopWords?: string[]; // Language-specific stop words for matching
characterReplacements?: Record<string, string>; // Language-specific char replacements (e.g. ß→ss)
minMBPerMinute?: number; // Drop results below this size/runtime ratio (default: off)
}

export interface EbookTorrentRequest {
Expand Down Expand Up @@ -120,11 +121,18 @@ export class RankingAlgorithm {
requireAuthor = true, // Safe default: require author in automatic mode
stopWords,
characterReplacements,
minMBPerMinute,
} = options;
// Filter out files < 20 MB (likely ebooks/samples)
const runtimeMinutes = audiobook.durationMinutes;
// Filter out files < 20 MB (likely ebooks/samples), and when runtime is known,
// files far too small to hold the whole book (single chapters from multi-file posts)
const filteredTorrents = torrents.filter((torrent) => {
const sizeMB = torrent.size / (1024 * 1024);
return sizeMB >= 20;
if (sizeMB < 20) return false;
if (minMBPerMinute && runtimeMinutes && runtimeMinutes > 0) {
return sizeMB / runtimeMinutes >= minMBPerMinute;
}
return true;
});

const ranked = filteredTorrents.map((torrent) => {
Expand Down
42 changes: 42 additions & 0 deletions tests/utils/ranking-algorithm.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,48 @@ describe('ranking-algorithm', () => {
expect(ranked[0].guid).toBe('big');
});

it('drops results below minMBPerMinute when runtime is known', () => {
// 20 h book: a single 57 MB chapter vs. a 600 MB full release
const chapter = { ...baseTorrent, guid: 'chapter', size: 57 * MB, seeders: 0 };
const full = { ...baseTorrent, guid: 'full', size: 600 * MB, seeders: 0 };

const ranked = rankTorrents(
[chapter, full],
{ title: 'Great Book', author: 'Author Name', durationMinutes: 1200 },
{ minMBPerMinute: 0.25 }
);

expect(ranked.map(r => r.guid)).toEqual(['full']);
});

it('keeps a complete ~29 kbps release (0.21 MB/min)', () => {
// Real complete release: 443 MB, 2154 min
const lowBitrate = { ...baseTorrent, guid: 'low', size: 443 * MB, seeders: 0 };
const chapter = { ...baseTorrent, guid: 'chapter', size: 100 * MB, seeders: 0 };

const ranked = rankTorrents(
[lowBitrate, chapter],
{ title: 'Great Book', author: 'Author Name', durationMinutes: 2154 },
{ minMBPerMinute: 0.15 }
);

expect(ranked.map(r => r.guid)).toEqual(['low']);
});

it('keeps small results when minMBPerMinute is unset or runtime is unknown', () => {
const chapter = { ...baseTorrent, guid: 'chapter', size: 57 * MB };

expect(rankTorrents(
[chapter],
{ title: 'Great Book', author: 'Author Name', durationMinutes: 1200 }
)).toHaveLength(1);
expect(rankTorrents(
[chapter],
{ title: 'Great Book', author: 'Author Name' },
{ minMBPerMinute: 0.25 }
)).toHaveLength(1);
});

it('prefers strong title/author matches over weaker ones', () => {
const good = { ...baseTorrent, guid: 'good', title: 'Great Book - Author Name' };
const bad = { ...baseTorrent, guid: 'bad', title: 'Different Title - Other Author' };
Expand Down