Add series fields to audiobooks and update related logic

Introduces 'series' and 'seriesPart' fields to the Audiobook model and database schema. Updates API routes, file organization, and path template utilities to support series metadata. Enhances chapter merging logic, improves notification backend testing, and expands test coverage for admin and API routes.

src/lib/integrations/audible.service.ts

@@ -23,6 +23,8 @@ export interface AudibleAudiobook {
   releaseDate?: string;
   rating?: number;
   genres?: string[];
+  series?: string;
+  seriesPart?: string;
 }
 
 export interface AudibleSearchResult {
@@ -492,6 +494,8 @@ export class AudibleService {
         releaseDate: data.releaseDate || undefined,
         rating: data.rating ? parseFloat(data.rating) : undefined,
         genres: data.genres?.map((g: any) => typeof g === 'string' ? g : g.name).slice(0, 5) || undefined,
+        series: data.seriesPrimary?.name || undefined,
+        seriesPart: data.seriesPrimary?.position || undefined,
       };
 
       // Ensure cover art URL is high quality
@@ -506,7 +510,9 @@ export class AudibleService {
         descLength: result.description?.length || 0,
         duration: result.durationMinutes,
         rating: result.rating,
-        genreCount: result.genres?.length || 0
+        genreCount: result.genres?.length || 0,
+        series: result.series,
+        seriesPart: result.seriesPart
       });
 
       return result;

src/lib/processors/download-torrent.processor.ts

@@ -60,6 +60,9 @@ export async function processDownloadTorrent(payload: DownloadTorrentPayload): P
       logger.info(`NZB added with ID: ${downloadClientId}`);
 
       // Create DownloadHistory record
+      // Determine indexer page URL - exclude magnet links from guid fallback
+      const indexerPageUrl = torrent.infoUrl || (torrent.guid?.startsWith('magnet:') ? null : torrent.guid);
+
       const downloadHistory = await prisma.downloadHistory.create({
         data: {
           requestId,
@@ -69,7 +72,7 @@ export async function processDownloadTorrent(payload: DownloadTorrentPayload): P
           torrentName: torrent.title,
           nzbId: downloadClientId, // Store NZB ID
           torrentSizeBytes: torrent.size,
-          torrentUrl: torrent.infoUrl || torrent.guid, // Indexer page URL (prefer infoUrl, fallback to guid)
+          torrentUrl: indexerPageUrl, // Indexer page URL (only if available and not a magnet/download link)
           magnetLink: torrent.downloadUrl, // Download URL (.nzb file)
           seeders: torrent.seeders || 0, // Usenet doesn't have seeders, but include for consistency
           leechers: 0,
@@ -121,6 +124,9 @@ export async function processDownloadTorrent(payload: DownloadTorrentPayload): P
       logger.info(`Torrent added with hash: ${downloadClientId}`);
 
       // Create DownloadHistory record
+      // Determine indexer page URL - exclude magnet links from guid fallback
+      const indexerPageUrl = torrent.infoUrl || (torrent.guid?.startsWith('magnet:') ? null : torrent.guid);
+
       const downloadHistory = await prisma.downloadHistory.create({
         data: {
           requestId,
@@ -130,7 +136,7 @@ export async function processDownloadTorrent(payload: DownloadTorrentPayload): P
           torrentName: torrent.title,
           torrentHash: torrent.infoHash || downloadClientId, // Store torrent hash
           torrentSizeBytes: torrent.size,
-          torrentUrl: torrent.infoUrl || torrent.guid, // Indexer page URL (prefer infoUrl, fallback to guid)
+          torrentUrl: indexerPageUrl, // Indexer page URL (only if available and not a magnet/download link)
           magnetLink: torrent.downloadUrl,
           seeders: torrent.seeders || 0,
           leechers: torrent.leechers || 0,

src/lib/processors/organize-files.processor.ts

@@ -94,6 +94,8 @@ export async function processOrganizeFiles(payload: OrganizeFilesPayload): Promi
         coverArtUrl: audiobook.coverArtUrl || undefined,
         asin: audiobook.audibleAsin || undefined,
         year,
+        series: audiobook.series || undefined,
+        seriesPart: audiobook.seriesPart || undefined,
       },
       template,
       jobId ? { jobId, context: 'FileOrganizer' } : undefined

src/lib/utils/chapter-merger.ts

@@ -447,6 +447,23 @@ function determineOutputBitrate(chapters: ChapterFile[]): string {
   return `${finalBitrate}k`;
 }
 
+/**
+ * Map bitrate to native AAC VBR quality value
+ * Quality range: 0.1-5 (higher = better quality/larger file)
+ */
+function bitrateToVbrQuality(bitrateStr: string): number {
+  const bitrate = parseInt(bitrateStr.replace('k', ''));
+
+  // Approximate mapping based on AAC VBR behavior
+  if (bitrate <= 64) return 1.0;   // ~64kbps
+  if (bitrate <= 96) return 1.5;   // ~96kbps
+  if (bitrate <= 128) return 2.0;  // ~128kbps
+  if (bitrate <= 160) return 2.5;  // ~160kbps
+  if (bitrate <= 192) return 3.0;  // ~192kbps
+  if (bitrate <= 256) return 4.0;  // ~256kbps
+  return 4.5; // ~320kbps+ (max quality)
+}
+
 /**
  * Check if libfdk_aac encoder is available (higher quality than native AAC)
  */
@@ -640,10 +657,12 @@ export async function mergeChapters(
         args.push('-vbr', '4'); // VBR mode 4 (~128-160kbps, high quality)
         await logger?.info(`Merge strategy: Re-encoding MP3 → AAC/M4B using libfdk_aac (high quality VBR, target ~${bitrate})`);
       } else {
+        // Use VBR for better quality at same average bitrate
+        const vbrQuality = bitrateToVbrQuality(bitrate);
         args.push('-c:a', 'aac');
-        args.push('-b:a', bitrate);
+        args.push('-q:a', vbrQuality.toString());
         args.push('-profile:a', 'aac_low'); // AAC-LC profile for maximum compatibility
-        await logger?.info(`Merge strategy: Re-encoding MP3 → AAC/M4B using native AAC at ${bitrate}`);
+        await logger?.info(`Merge strategy: Re-encoding MP3 → AAC/M4B using native AAC VBR (quality ${vbrQuality}, target ~${bitrate})`);
       }
     } else {
       // M4A/M4B -> M4B can use codec copy (fast, lossless)
@@ -838,7 +857,7 @@ async function validateMergedFile(
     const stats = await fs.stat(outputPath);
     const sizeMB = stats.size / 1024 / 1024;
     const durationMinutes = expectedDuration / 1000 / 60;
-    const expectedMinSize = durationMinutes * 0.5; // ~0.5MB per minute minimum for compressed audio
+    const expectedMinSize = durationMinutes * 0.4; // ~0.4MB per minute minimum (accommodates 64kbps encoding)
 
     if (sizeMB < expectedMinSize) {
       return {

src/lib/utils/file-organizer.ts

@@ -30,6 +30,8 @@ export interface AudiobookMetadata {
   year?: number;
   coverArtUrl?: string;
   asin?: string;
+  series?: string;
+  seriesPart?: string;
 }
 
 export interface OrganizationResult {
@@ -275,7 +277,9 @@ export class FileOrganizer {
         audiobook.title,
         audiobook.narrator,
         audiobook.asin,
-        audiobook.year
+        audiobook.year,
+        audiobook.series,
+        audiobook.seriesPart
       );
 
       await logger?.info(`Target path: ${targetPath}`);
@@ -556,7 +560,9 @@ export class FileOrganizer {
     title: string,
     narrator?: string,
     asin?: string,
-    year?: number
+    year?: number,
+    series?: string,
+    seriesPart?: string
   ): string {
     const variables: TemplateVariables = {
       author,
@@ -564,6 +570,8 @@ export class FileOrganizer {
       narrator,
       asin,
       year,
+      series,
+      seriesPart,
     };
 
     const relativePath = substituteTemplate(template, variables);
@@ -713,7 +721,7 @@ export async function getFileOrganizer(): Promise<FileOrganizer> {
 export function buildAudiobookPath(
   baseDir: string,
   template: string,
-  variables: { author: string; title: string; narrator?: string; asin?: string; year?: number }
+  variables: { author: string; title: string; narrator?: string; asin?: string; year?: number; series?: string; seriesPart?: string }
 ): string {
   const templateVars: TemplateVariables = {
     author: variables.author,
@@ -721,6 +729,8 @@ export function buildAudiobookPath(
     narrator: variables.narrator,
     asin: variables.asin,
     year: variables.year,
+    series: variables.series,
+    seriesPart: variables.seriesPart,
   };
 
   const relativePath = substituteTemplate(template, templateVars);

src/lib/utils/path-template.util.ts

@@ -15,6 +15,8 @@ export interface TemplateVariables {
   narrator?: string;
   asin?: string;
   year?: number;
+  series?: string;
+  seriesPart?: string;
 }
 
 /**
@@ -28,7 +30,7 @@ export interface ValidationResult {
 /**
  * Supported template variable names
  */
-const VALID_VARIABLES = ['author', 'title', 'narrator', 'asin', 'year'];
+const VALID_VARIABLES = ['author', 'title', 'narrator', 'asin', 'year', 'series', 'seriesPart'];
 
 /**
  * Invalid file path characters (outside of template variables)
@@ -228,14 +230,18 @@ export function generateMockPreviews(template: string): string[] {
       title: 'Mistborn: The Final Empire',
       narrator: 'Michael Kramer',
       asin: 'B002UZMLXM',
-      year: 2006
+      year: 2006,
+      series: 'The Mistborn Saga',
+      seriesPart: '1'
     },
     {
       author: 'Douglas Adams',
       title: "The Hitchhiker's Guide to the Galaxy",
       narrator: 'Stephen Fry',
       asin: 'B0009JKV9W',
-      year: 2005
+      year: 2005,
+      series: "Hitchhiker's Guide",
+      seriesPart: '1'
     },
     {
       author: 'Andy Weir',
@@ -243,6 +249,7 @@ export function generateMockPreviews(template: string): string[] {
       // No narrator for this example
       asin: 'B08G9PRS1K',
       year: 2021
+      // No series data - to test empty handling
     }
   ];