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/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
     }
   ];