Add Plex format coercion (.mp4 → .m4b)

Implement Plex-compatible file-extension coercion to avoid Plex silently ignoring .mp4 (and single-file .m4a) audiobooks (issue #166). Adds a DB migration and configuration key (plex_format_coercion_enabled, default true), exposes a toggle in the setup wizard and Admin Paths settings, and persists/reads the setting in the admin/setup APIs.

Introduces src/lib/utils/format-coercion.ts (coerceToPlexCompatible) and related constants in src/lib/constants/audio-formats.ts (PLEX_COMPATIBLE_EXTENSIONS, COERCION_RENAME_MAP, DRM_EXTENSIONS, TRANSCODE_REQUIRED_EXTENSIONS). The organize-files processor now runs coercion after organizing/tagging and before generating the filesHash and triggering scans; coercion is idempotent, never overwrites existing targets, logs warnings on DRM/transcode/permission errors, and is non-fatal.

Adds unit tests for the coercion util and updates processor & setup UI tests. Updates documentation (TABLEOFCONTENTS, file-organization, fixes/file-hash-matching, settings-pages) describing behavior, config, and constraints.

tests/app/setup/steps/PathsStep.test.tsx

@@ -23,6 +23,7 @@ const PathsHarness = ({
     downloadDir: '/downloads',
     mediaDir: '/media/audiobooks',
     metadataTaggingEnabled: true,
+    plexFormatCoercionEnabled: true,
     chapterMergingEnabled: false,
     ...initialState,
   });
@@ -84,7 +85,11 @@ describe('PathsStep', () => {
       <PathsHarness
         onNext={vi.fn()}
         onBack={vi.fn()}
-        initialState={{ metadataTaggingEnabled: false, chapterMergingEnabled: false }}
+        initialState={{
+          metadataTaggingEnabled: false,
+          plexFormatCoercionEnabled: false,
+          chapterMergingEnabled: false,
+        }}
       />
     );
 
@@ -97,4 +102,18 @@ describe('PathsStep', () => {
     expect(metadataToggle).toBeChecked();
     expect(chapterToggle).toBeChecked();
   });
+
+  it('renders plex format coercion toggle with default checked and toggles state', async () => {
+    render(<PathsHarness onNext={vi.fn()} onBack={vi.fn()} />);
+
+    const coercionToggle = screen.getByLabelText('Coerce file formats for Plex compatibility');
+
+    expect(coercionToggle).toBeChecked();
+
+    fireEvent.click(coercionToggle);
+    expect(coercionToggle).not.toBeChecked();
+
+    fireEvent.click(coercionToggle);
+    expect(coercionToggle).toBeChecked();
+  });
 });

tests/processors/organize-files.processor.test.ts

@@ -5,6 +5,7 @@
 
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { createPrismaMock } from '../helpers/prisma';
+import { generateFilesHash } from '@/lib/utils/files-hash';
 
 const prismaMock = createPrismaMock();
 const organizerMock = vi.hoisted(() => ({ organize: vi.fn() }));
@@ -16,6 +17,9 @@ const configMock = vi.hoisted(() => ({
   getBackendMode: vi.fn(),
   get: vi.fn(),
 }));
+const formatCoercionMock = vi.hoisted(() => ({
+  coerceToPlexCompatible: vi.fn(),
+}));
 
 vi.mock('@/lib/db', () => ({
   prisma: prismaMock,
@@ -37,6 +41,8 @@ vi.mock('@/lib/services/job-queue.service', () => ({
   getJobQueueService: () => jobQueueMock,
 }));
 
+vi.mock('@/lib/utils/format-coercion', () => formatCoercionMock);
+
 describe('processOrganizeFiles', () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -46,6 +52,13 @@ describe('processOrganizeFiles', () => {
       type: 'audiobook', // Default to audiobook type
       user: { plexUsername: 'testuser' },
     });
+    // Default passthrough for Plex format coercion (issue #166): leave audio files unchanged
+    formatCoercionMock.coerceToPlexCompatible.mockImplementation(async (paths: string[]) => ({
+      renamed: [],
+      warnings: [],
+      errors: [],
+      finalAudioFiles: paths,
+    }));
   });
 
   it('organizes files and triggers filesystem scan when enabled', async () => {
@@ -398,6 +411,162 @@ describe('processOrganizeFiles', () => {
     );
   });
 
+  it('calls Plex format coercion when enabled (default)', async () => {
+    prismaMock.audiobook.findUnique.mockResolvedValue({
+      id: 'a-coerce-on',
+      title: 'Book',
+      author: 'Author',
+      narrator: null,
+      coverArtUrl: null,
+      audibleAsin: 'ASIN-CO1',
+    });
+    // configuration.findUnique returns undefined (no setting persisted) -> default-on
+    prismaMock.configuration.findUnique.mockResolvedValue(undefined);
+    organizerMock.organize.mockResolvedValue({
+      success: true,
+      targetPath: '/media/Author/Book',
+      filesMovedCount: 1,
+      errors: [],
+      audioFiles: ['/media/Author/Book/Book.mp4'],
+    });
+    configMock.getBackendMode.mockResolvedValue('plex');
+    configMock.get.mockResolvedValue('false');
+
+    const { processOrganizeFiles } = await import('@/lib/processors/organize-files.processor');
+    const result = await processOrganizeFiles({
+      requestId: 'req-coerce-on',
+      audiobookId: 'a-coerce-on',
+      downloadPath: '/downloads/book',
+      jobId: 'job-coerce-on',
+    });
+
+    expect(result.success).toBe(true);
+    expect(formatCoercionMock.coerceToPlexCompatible).toHaveBeenCalledWith(
+      ['/media/Author/Book/Book.mp4'],
+      expect.anything()
+    );
+  });
+
+  it('skips Plex format coercion when disabled', async () => {
+    prismaMock.audiobook.findUnique.mockResolvedValue({
+      id: 'a-coerce-off',
+      title: 'Book',
+      author: 'Author',
+      narrator: null,
+      coverArtUrl: null,
+      audibleAsin: 'ASIN-CO2',
+    });
+    prismaMock.configuration.findUnique.mockImplementation(async (args: any) => {
+      if (args?.where?.key === 'plex_format_coercion_enabled') {
+        return { key: 'plex_format_coercion_enabled', value: 'false' };
+      }
+      return undefined;
+    });
+    organizerMock.organize.mockResolvedValue({
+      success: true,
+      targetPath: '/media/Author/Book',
+      filesMovedCount: 1,
+      errors: [],
+      audioFiles: ['/media/Author/Book/Book.mp4'],
+    });
+    configMock.getBackendMode.mockResolvedValue('plex');
+    configMock.get.mockResolvedValue('false');
+
+    const { processOrganizeFiles } = await import('@/lib/processors/organize-files.processor');
+    const result = await processOrganizeFiles({
+      requestId: 'req-coerce-off',
+      audiobookId: 'a-coerce-off',
+      downloadPath: '/downloads/book',
+      jobId: 'job-coerce-off',
+    });
+
+    expect(result.success).toBe(true);
+    expect(formatCoercionMock.coerceToPlexCompatible).not.toHaveBeenCalled();
+  });
+
+  it('coercion failure does NOT mark request failed', async () => {
+    prismaMock.audiobook.findUnique.mockResolvedValue({
+      id: 'a-coerce-throw',
+      title: 'Book',
+      author: 'Author',
+      narrator: null,
+      coverArtUrl: null,
+      audibleAsin: 'ASIN-CO3',
+    });
+    prismaMock.configuration.findUnique.mockResolvedValue(undefined);
+    organizerMock.organize.mockResolvedValue({
+      success: true,
+      targetPath: '/media/Author/Book',
+      filesMovedCount: 1,
+      errors: [],
+      audioFiles: ['/media/Author/Book/Book.mp4'],
+    });
+    formatCoercionMock.coerceToPlexCompatible.mockRejectedValueOnce(new Error('boom'));
+    configMock.getBackendMode.mockResolvedValue('plex');
+    configMock.get.mockResolvedValue('false');
+
+    const { processOrganizeFiles } = await import('@/lib/processors/organize-files.processor');
+    const result = await processOrganizeFiles({
+      requestId: 'req-coerce-throw',
+      audiobookId: 'a-coerce-throw',
+      downloadPath: '/downloads/book',
+      jobId: 'job-coerce-throw',
+    });
+
+    expect(result.success).toBe(true);
+    expect(prismaMock.request.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ status: 'downloaded' }),
+      })
+    );
+  });
+
+  it('filesHash reflects post-coercion filenames', async () => {
+    prismaMock.audiobook.findUnique.mockResolvedValue({
+      id: 'a-coerce-hash',
+      title: 'Book',
+      author: 'Author',
+      narrator: null,
+      coverArtUrl: null,
+      audibleAsin: 'ASIN-CO4',
+    });
+    prismaMock.configuration.findUnique.mockResolvedValue(undefined);
+    organizerMock.organize.mockResolvedValue({
+      success: true,
+      targetPath: '/media/Author/Book',
+      filesMovedCount: 1,
+      errors: [],
+      audioFiles: ['/media/Book.mp4'],
+    });
+    // Coercion renames .mp4 -> .m4b
+    formatCoercionMock.coerceToPlexCompatible.mockResolvedValueOnce({
+      renamed: [{ from: '/media/Book.mp4', to: '/media/Book.m4b' }],
+      warnings: [],
+      errors: [],
+      finalAudioFiles: ['/media/Book.m4b'],
+    });
+    configMock.getBackendMode.mockResolvedValue('plex');
+    configMock.get.mockResolvedValue('false');
+
+    const { processOrganizeFiles } = await import('@/lib/processors/organize-files.processor');
+    const result = await processOrganizeFiles({
+      requestId: 'req-coerce-hash',
+      audiobookId: 'a-coerce-hash',
+      downloadPath: '/downloads/book',
+      jobId: 'job-coerce-hash',
+    });
+
+    expect(result.success).toBe(true);
+    const expectedHash = generateFilesHash(['/media/Book.m4b']);
+    expect(expectedHash).toMatch(/^[a-f0-9]{64}$/);
+    expect(prismaMock.audiobook.update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { id: 'a-coerce-hash' },
+        data: expect.objectContaining({ filesHash: expectedHash }),
+      })
+    );
+  });
+
   it('generates and stores filesHash after successful organization', async () => {
     prismaMock.request.update.mockResolvedValue({});
     prismaMock.audiobook.findUnique.mockResolvedValue({

tests/utils/format-coercion.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Component: Plex Format Coercion Tests
+ * Documentation: documentation/phase3/file-organization.md
+ */
+
+import path from 'path';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { coerceToPlexCompatible } from '@/lib/utils/format-coercion';
+
+const fsMock = vi.hoisted(() => ({
+  access: vi.fn(),
+  rename: vi.fn(),
+}));
+
+vi.mock('fs', () => ({
+  promises: fsMock,
+  default: { promises: fsMock },
+}));
+
+/** Make `fs.access` reject with ENOENT (target does not exist) for every path. */
+function targetMissing(): void {
+  fsMock.access.mockImplementation(() => {
+    const err = new Error('ENOENT: no such file or directory') as NodeJS.ErrnoException;
+    err.code = 'ENOENT';
+    return Promise.reject(err);
+  });
+}
+
+/** Make `fs.rename` resolve successfully. */
+function renameOk(): void {
+  fsMock.rename.mockResolvedValue(undefined);
+}
+
+function makeLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  };
+}
+
+describe('coerceToPlexCompatible', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('happy paths', () => {
+    it('renames .mp4 to .m4b', async () => {
+      targetMissing();
+      renameOk();
+      const input = ['/media/Book/Book.mp4'];
+
+      const result = await coerceToPlexCompatible(input);
+
+      expect(result.renamed).toEqual([{ from: '/media/Book/Book.mp4', to: path.join('/media/Book', 'Book.m4b') }]);
+      expect(result.finalAudioFiles).toEqual([path.join('/media/Book', 'Book.m4b')]);
+      expect(result.warnings).toEqual([]);
+      expect(fsMock.rename).toHaveBeenCalledTimes(1);
+    });
+
+    it('renames single-file .m4a to .m4b', async () => {
+      targetMissing();
+      renameOk();
+      const input = ['/media/Book/Book.m4a'];
+
+      const result = await coerceToPlexCompatible(input);
+
+      expect(result.renamed).toEqual([{ from: '/media/Book/Book.m4a', to: path.join('/media/Book', 'Book.m4b') }]);
+      expect(result.finalAudioFiles).toEqual([path.join('/media/Book', 'Book.m4b')]);
+      expect(result.warnings).toEqual([]);
+    });
+
+    it('leaves multi-file .m4a audiobooks alone (more than one .m4a in same dir)', async () => {
+      targetMissing();
+      renameOk();
+      const input = ['/media/Book/Chapter01.m4a', '/media/Book/Chapter02.m4a'];
+
+      const result = await coerceToPlexCompatible(input);
+
+      expect(result.renamed).toEqual([]);
+      expect(result.finalAudioFiles).toEqual(input);
+      expect(fsMock.rename).not.toHaveBeenCalled();
+    });
+
+    it('handles mixed .mp4 + .mp3: renames mp4, leaves mp3 untouched', async () => {
+      targetMissing();
+      renameOk();
+      const input = ['/media/Book/Book.mp4', '/media/Other/Intro.mp3'];
+
+      const result = await coerceToPlexCompatible(input);
+
+      expect(result.renamed).toEqual([
+        { from: '/media/Book/Book.mp4', to: path.join('/media/Book', 'Book.m4b') },
+      ]);
+      expect(result.finalAudioFiles).toEqual([
+        path.join('/media/Book', 'Book.m4b'),
+        '/media/Other/Intro.mp3',
+      ]);
+      expect(fsMock.rename).toHaveBeenCalledTimes(1);
+    });
+
+    it('returns empty result for empty input', async () => {
+      const result = await coerceToPlexCompatible([]);
+      expect(result).toEqual({ renamed: [], warnings: [], errors: [], finalAudioFiles: [] });
+      expect(fsMock.rename).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('already-compatible inputs (sanity)', () => {
+    it('is a silent no-op for already-Plex-compatible files (.m4b/.mp3/.flac)', async () => {
+      targetMissing();
+      renameOk();
+      const input = [
+        '/media/Book/Book.m4b',
+        '/media/Other/Track.mp3',
+        '/media/Third/Track.flac',
+      ];
+
+      const result = await coerceToPlexCompatible(input);
+
+      expect(result.renamed).toEqual([]);
+      expect(result.warnings).toEqual([]);
+      expect(result.finalAudioFiles).toEqual(input);
+      expect(fsMock.rename).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('DRM and transcode-required formats', () => {
+    it('warns on .aa (DRM) and skips rename', async () => {
+      const logger = makeLogger();
+      const input = ['/media/Book/Book.aa'];
+
+      const result = await coerceToPlexCompatible(input, logger as never);
+
+      expect(result.renamed).toEqual([]);
+      expect(result.finalAudioFiles).toEqual(input);
+      expect(result.warnings.length).toBe(1);
+      expect(result.warnings[0]).toMatch(/DRM/i);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      expect(fsMock.rename).not.toHaveBeenCalled();
+    });
+
+    it('warns on .aax (DRM) and skips rename', async () => {
+      const input = ['/media/Book/Book.aax'];
+
+      const result = await coerceToPlexCompatible(input);
+
+      expect(result.renamed).toEqual([]);
+      expect(result.warnings.length).toBe(1);
+      expect(result.warnings[0]).toMatch(/DRM/i);
+      expect(result.finalAudioFiles).toEqual(input);
+    });
+
+    it('warns on .ogg (transcode-required) and skips rename', async () => {
+      const logger = makeLogger();
+      const input = ['/media/Book/Book.ogg'];
+
+      const result = await coerceToPlexCompatible(input, logger as never);
+
+      expect(result.renamed).toEqual([]);
+      expect(result.warnings.length).toBe(1);
+      expect(result.warnings[0]).toMatch(/transcode/i);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+      expect(result.finalAudioFiles).toEqual(input);
+    });
+  });
+
+  describe('idempotency (collision)', () => {
+    it('does not overwrite an existing target file', async () => {
+      // First access resolves (target exists), rename should not be called.
+      fsMock.access.mockResolvedValue(undefined);
+      const logger = makeLogger();
+      const input = ['/media/Book/Book.mp4'];
+
+      const result = await coerceToPlexCompatible(input, logger as never);
+
+      expect(result.renamed).toEqual([]);
+      expect(result.finalAudioFiles).toEqual(input);
+      expect(result.warnings.length).toBe(1);
+      expect(result.warnings[0]).toMatch(/already exists/i);
+      expect(fsMock.rename).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('rename failures', () => {
+    it('captures EPERM as a warning and preserves the original path', async () => {
+      targetMissing();
+      const epermErr = new Error('EPERM: operation not permitted') as NodeJS.ErrnoException;
+      epermErr.code = 'EPERM';
+      fsMock.rename.mockRejectedValueOnce(epermErr);
+      const logger = makeLogger();
+      const input = ['/media/Book/Book.mp4'];
+
+      const result = await coerceToPlexCompatible(input, logger as never);
+
+      expect(result.renamed).toEqual([]);
+      expect(result.finalAudioFiles).toEqual(input);
+      expect(result.warnings.length).toBe(1);
+      expect(result.warnings[0]).toMatch(/EPERM/);
+      expect(logger.warn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('logger contract', () => {
+    it('works without a logger (optional parameter)', async () => {
+      targetMissing();
+      renameOk();
+      const input = ['/media/Book/Book.mp4'];
+
+      // Must not throw when logger is omitted.
+      const result = await coerceToPlexCompatible(input);
+
+      expect(result.renamed.length).toBe(1);
+      expect(result.finalAudioFiles).toEqual([path.join('/media/Book', 'Book.m4b')]);
+    });
+  });
+});